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