The Ferrocene Language Specification (FLS) is a document describing the Rust language. It was created as one of the prerequisites for qualifying Ferrocene, a Rust toolchain qualified for safety-critical environments. The FLS is compiled of existing Rust documentation, but presented with a rigorous structure in order to meet the requirements of qualification.
The FLS is not intended to be used as the normative specification of the Rust language, nor is it meant to replace the decision-making processes of the Rust project. Any difference between the FLS and the behavior of the Rust compiler is considered an error on our part and the FLS will be updated accordingly.
The Ferrocene Language Specification text is licensed under either the MIT
or Apache-2.0 licenses, at your option. Individual files might have
different licensing. Licensing metadata is present in each file, and the full
licenses text is present in the LICENSES/ directory.
FLS uses Sphinx to build a rendered version of the specification. To
simplify building the rendered version, we created a script called make.py
that takes care of installing the expected Sphinx release and invoking it with
the right flags.
You can build the rendered version by running:
./make.py
By default, Sphinx uses incremental rebuilds to generate the content that
changed since the last invocation. If you notice a problem with incremental
rebuilds, you can pass the -c flag to clear the existing artifacts before
building:
./make.py -c
The rendered version will be available in build/html/.
You can also start a local server on port 8000 with automatic rebuild and
reload whenever you change a file by passing the -s flag:
./make.py -s
It's possible to run Rust's linkchecker tool on the rendered documentation, to
see if there are broken links. To do so, pass the --check-links flag:
./make.py --check-links
This will clone the source code of the tool, build it, and execute it on the rendered documentation.
The FLS uses pip-tools to manage the Python dependencies used for builds,
as it allows pinning hashes for the dependencies. While it doesn't add any
additional burden when installing dependencies (the format it outputs is
understood by pip), you have to install it when regenerating the
requirements.txt file.
To install pip-tools, we recommend first installing pipx, and then running:
pipx install pip-tools
Once that's done, you can change the list of desired dependencies in the
requirements.in file, and run this command to regenerate the
requirements.txt file:
pip-compile --generate-hashes