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.