Ferrocene Documentation › Language Specification
Ferrocene logo

Language Specification

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 The unsafe keyword of a module is rejected, but may still be consumed by macros.

18.2:3 An inline module is a module with an InlineModuleSpecification.

18.2:4 An outline module is a module with an OutlineModuleSpecification.

18.2:5 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:6 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 The crate type of a crate is the value of the attribute crate_type of a crate or the value of --crate-type flag passed to the tool compiling the crate.

18.3:3 The crate type of a crate if not specified is bin.

18.3:4 A crate may be subject to multiple crate types, treating each type as a separate crate.

18.3:5 A binary crate is a crate whose crate type is bin.

18.3:6 A binary crate that is not subject to attribute no_main shall have a function in scope of its crate root module under the name main with a main function signature.

18.3:7 The function in scope of a binary crate‘s crate root module under the name main with a main function signature is the binary crate‘s program entry point.

18.3:8 A library crate is a crate whose crate type is lib, rlib, staticlib, dylib, or cdylib.

18.3:9 A proc-macro crate is a crate whose crate type is proc-macro.

18.3:10 A proc-macro crate shall not declare items in its crate root module with public visibility unless the item is a procedural macro.

18.3:11 Only a proc-macro crate shall declare procedural macros.

18.4. Crate Imports

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 with an identifier 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 A crate root module subject to attribute cfg where the related configuration predicate evaluates to false is considered empty except for all attributes up to the invoked attribute cfg.

18.6:5 An attribute cfg_attr where the related configuration predicate evaluates to false is not considered part of a Rust program.

18.7. Program Entry Point

Legality Rules

18.7:1 A program entry point is a function that is invoked at the start of a Rust program.

18.7:2 A main function signature is a function signature subject to the following restrictions: