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? mod Name 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 that 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.

18.2:8 The following attributes apply to modules:

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. A crate contains a tree of nested module scopes.

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. External Crates

Syntax

ExternalCrateImport ::=
    extern crate CrateIndication 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.4:8 The following attributes apply to crate imports:

18.5. Compilation Roots

Legality Rules

18.5:1 A crate root module is the root of the nested module scopes 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.

18.6:5 An attribute cfg_attr where the related configuration predicate evaluates to true is replaced with a new attribute for each AttributeContent in the attribute’s AttributeContentList.