From d1f046fe895d9b7c5e5480d0128f0d161bedcba8 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Mon, 20 Feb 2017 23:25:58 -0500 Subject: [PATCH] Crates and source files --- .../reference/src/crates-and-source-files.md | 33 +++++++++++-------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/src/doc/reference/src/crates-and-source-files.md b/src/doc/reference/src/crates-and-source-files.md index dbb7098f7f140..d41a8dc964095 100644 --- a/src/doc/reference/src/crates-and-source-files.md +++ b/src/doc/reference/src/crates-and-source-files.md @@ -13,24 +13,16 @@ semantic rules that have a *dynamic interpretation* govern the behavior of the program at run-time. -[^phase-distinction]: This distinction would also exist in an interpreter. - Static checks like syntactic analysis, type checking, and lints should - happen before the program is executed regardless of when it is executed. - The compilation model centers on artifacts called _crates_. Each compilation processes a single crate in source form, and if successful, produces a single crate in binary form: either an executable or some sort of library.[^cratesourcefile] -[^cratesourcefile]: A crate is somewhat analogous to an *assembly* in the - ECMA-335 CLI model, a *library* in the SML/NJ Compilation Manager, a *unit* - in the Owens and Flatt module system, or a *configuration* in Mesa. - A _crate_ is a unit of compilation and linking, as well as versioning, distribution and runtime loading. A crate contains a _tree_ of nested -[module](#modules) scopes. The top level of this tree is a module that is +[module] scopes. The top level of this tree is a module that is anonymous (from the point of view of paths within the module) and any item -within a crate has a canonical [module path](#paths) denoting its location +within a crate has a canonical [module path] denoting its location within the crate's module tree. The Rust compiler is always invoked with a single source file as input, and @@ -42,16 +34,16 @@ A Rust source file describes a module, the name and location of which — in the module tree of the current crate — are defined from outside the source file: either by an explicit `mod_item` in a referencing source file, or by the name of the crate itself. Every source file is a module, but not every -module needs its own source file: [module definitions](#modules) can be nested +module needs its own source file: [module definitions][module] can be nested within one file. Each source file contains a sequence of zero or more `item` definitions, and -may optionally begin with any number of [attributes](#items-and-attributes) +may optionally begin with any number of [attributes] that apply to the containing module, most of which influence the behavior of the compiler. The anonymous crate module can have additional attributes that apply to the crate as a whole. -```no_run +```rust,no_run // Specify the crate name. #![crate_name = "projx"] @@ -65,4 +57,17 @@ apply to the crate as a whole. A crate that contains a `main` function can be compiled to an executable. If a `main` function is present, its return type must be `()` -("[unit](#tuple-types)") and it must take no arguments. +("[unit]") and it must take no arguments. + +[^phase-distinction]: This distinction would also exist in an interpreter. + Static checks like syntactic analysis, type checking, and lints should + happen before the program is executed regardless of when it is executed. + +[^cratesourcefile]: A crate is somewhat analogous to an *assembly* in the + ECMA-335 CLI model, a *library* in the SML/NJ Compilation Manager, a *unit* + in the Owens and Flatt module system, or a *configuration* in Mesa. + +[module]: items.html#modules +[module path]: paths.html +[attributes]: items-and-attributes.html +[unit]: types.html#tuple-types \ No newline at end of file