Skip to content

Commit 1447ee4

Browse files
committed
Rollup merge of #24727 - rkruppe:reference-audit, r=steveklabnik
It was in pretty good shape, but since that is my pet peeve, I clarified the compiler/interpreter distinction and why it is irrelevant for this section. Otherwise only a couple of minor clarifications, and weasel words where reality is more complicated than the text accounted for (e.g., there is more than one kind of library). r? @steveklabnik
2 parents 0c1df5d + e9f2980 commit 1447ee4

File tree

1 file changed

+25
-10
lines changed

1 file changed

+25
-10
lines changed

src/doc/reference.md

+25-10
Original file line numberDiff line numberDiff line change
@@ -738,15 +738,26 @@ Rust syntax is restricted in two ways:
738738

739739
# Crates and source files
740740

741-
Rust is a *compiled* language. Its semantics obey a *phase distinction* between
742-
compile-time and run-time. Those semantic rules that have a *static
741+
Although Rust, like any other language, can be implemented by an interpreter as
742+
well as a compiler, the only existing implementation is a compiler —
743+
from now on referred to as *the* Rust compiler — and the language has
744+
always been designed to be compiled. For these reasons, this section assumes a
745+
compiler.
746+
747+
Rust's semantics obey a *phase distinction* between compile-time and
748+
run-time.[^phase-distinction] Those semantic rules that have a *static
743749
interpretation* govern the success or failure of compilation. Those semantics
744750
that have a *dynamic interpretation* govern the behavior of the program at
745751
run-time.
746752

753+
[^phase-distinction]: This distinction would also exist in an interpreter.
754+
Static checks like syntactic analysis, type checking, and lints should
755+
happen before the program is executed regardless of when it is executed.
756+
747757
The compilation model centers on artifacts called _crates_. Each compilation
748758
processes a single crate in source form, and if successful, produces a single
749-
crate in binary form: either an executable or a library.[^cratesourcefile]
759+
crate in binary form: either an executable or some sort of
760+
library.[^cratesourcefile]
750761

751762
[^cratesourcefile]: A crate is somewhat analogous to an *assembly* in the
752763
ECMA-335 CLI model, a *library* in the SML/NJ Compilation Manager, a *unit*
@@ -767,21 +778,25 @@ extension `.rs`.
767778
A Rust source file describes a module, the name and location of which —
768779
in the module tree of the current crate — are defined from outside the
769780
source file: either by an explicit `mod_item` in a referencing source file, or
770-
by the name of the crate itself.
781+
by the name of the crate itself. Every source file is a module, but not every
782+
module needs its own source file: [module definitions](#modules) can be nested
783+
within one file.
771784

772785
Each source file contains a sequence of zero or more `item` definitions, and
773-
may optionally begin with any number of `attributes` that apply to the
774-
containing module. Attributes on the anonymous crate module define important
775-
metadata that influences the behavior of the compiler.
786+
may optionally begin with any number of [attributes](#Items and attributes)
787+
that apply to the containing module, most of which influence the behavior of
788+
the compiler. The anonymous crate module can have additional attributes that
789+
apply to the crate as a whole.
776790

777791
```no_run
778-
// Crate name
792+
// Specify the crate name.
779793
#![crate_name = "projx"]
780794
781-
// Specify the output type
795+
// Specify the type of output artifact.
782796
#![crate_type = "lib"]
783797
784-
// Turn on a warning
798+
// Turn on a warning.
799+
// This can be done in any module, not just the anonymous crate module.
785800
#![warn(non_camel_case_types)]
786801
```
787802

0 commit comments

Comments
 (0)