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.
18. Program Structure and Compilation¶
18.1. Source Files¶
Syntax
SourceFile
::=ZeroWidthNoBreakSpace
?Shebang
?InnerAttributeOrDoc
*Item
*ZeroWidthNoBreakSpace
::= \u{FEFF}Shebang
::= #! ~[NewLine
]*NewLine
::= \n
Legality Rules
18.1:1 A source file contains the program text consisting of inner attributes, inner doc comments, and items. The location of a source file is tool defined.
18.1:2
A Shebang
does not have an effect on the compilation.
18.2. Modules¶
Syntax
ModuleDeclaration
::= unsafe? modName
ModuleSpecification
ModuleSpecification
::=InlineModuleSpecification
|OutlineModuleSpecification
InlineModuleSpecification
::= {InnerAttributeOrDoc
*Item
* }OutlineModuleSpecification
::= ;
Legality Rules
18.2:1 A module is a container for zero or more items.
18.2:2
An unsafe module is a module subject to keyword unsafe
.
18.2:3
The unsafe
keyword of an unsafe module is rejected, but may still
be consumed by macros.
18.2:4
An inline module is a module with an InlineModuleSpecification
.
18.2:5
An outline module is a module with an OutlineModuleSpecification
.
18.2:6 An outline module loads a source file and considers the text of the source file to be inlined within the context of the outline module.
18.2:7
The location of a module source file can be specified using
attribute path
.
Examples
#[path = "path/to/module"]
pub mod module {
#![allow(dead_code)]
struct Struct;
pub mod other;
}
18.3. Crates¶
Legality Rules
18.3:1 A crate is a unit of compilation and linking that contains a tree of nested modules.
18.3:2 A binary crate is a crate that contains a main function. A tool can compile a binary crate to an executable.
18.3:3
A library crate is either a crate without a main function or a
crate subject to attribute no_main
. A tool is free to compile a
library crate to a shared library.
18.3:4 A proc-macro crate is a crate that contains procedural macros. A tool is free to compile a proc-macro crate to a shared library.
18.3:5 A proc-macro crate shall not declare items with public visibility unless the item is a procedural macro.
18.3:6 Only a proc-macro crate shall declare procedural macros.
18.4. Crate Imports¶
Syntax
ExternalCrateImport
::= extern crateCrateIndication
Renaming
? ;CrateIndication
::=Identifier
| self
Legality Rules
18.4:1 A crate import specifies a required dependency on an external crate.
18.4:2 A crate indication is a construct that indicates a crate.
18.4:3 A crate import binds an external crate to its crate indication.
18.4:4
Crate indication self
shall require a renaming.
18.4:5 A crate import with a renaming binds the external crate to a local name and introduces the local name into the enclosing scope.
18.4:6 If a crate import appears at the crate root module, then the crate indication is added to the external prelude.
18.4:7 A crate indication shall resolve to an external crate. The process of resolving a crate indication to an external crate is tool-defined.
18.5. Compilation Roots¶
Legality Rules
18.5:1 A crate root module is the root of the nested module tree of a crate.
18.5:2 A tool can define a crate root module for a single crate.
18.5:3 A compilation root is an input to a compilation performed by a tool. A crate root module is a compilation root.
18.6. Conditional Compilation¶
Legality Rules
18.6:1 Conditionally-compiled source code is source code that may or may not be considered a part of a Rust program depending on configuration predicates.
18.6:2 Conditional compilation is the process of compiling conditionally-compiled source code.
18.6:3
A construct subject to attribute cfg
where the related
configuration predicate evaluates to false
is not considered part of a
Rust program.
18.6:4
An attribute cfg_attr
where the related configuration predicate
evaluates to false
is not considered part of a Rust program.