From 8e35b8cbab5b4e68cbbe0f6fe0725070e0e31d52 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 13 Aug 2024 14:51:02 -0400 Subject: [PATCH 1/3] Add spec identifiers to crates-and-source-files.md --- src/crates-and-source-files.md | 36 ++++++++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index 426ee26f1..40538f09d 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -1,5 +1,8 @@ # Crates and source files +r[crate] + +r[crate.syntax] > **Syntax**\ > _Crate_ :\ >    [_InnerAttribute_]\*\ @@ -10,17 +13,20 @@ > compiler, and the language has always been designed to be compiled. For these > reasons, this section assumes a compiler. +r[crate.compile-time] Rust's semantics obey a *phase distinction* between compile-time and run-time.[^phase-distinction] Semantic rules that have a *static interpretation* govern the success or failure of compilation, while semantic rules that have a *dynamic interpretation* govern the behavior of the program at run-time. +r[crate.unit] 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] +r[crate.module] 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] scopes. The top level of this tree is a module that is @@ -28,22 +34,31 @@ anonymous (from the point of view of paths within the module) and any item within a crate has a canonical [module path] denoting its location within the crate's module tree. +r[crate.input-source] The Rust compiler is always invoked with a single source file as input, and always produces a single output crate. The processing of that source file may result in other source files being loaded as modules. Source files have the extension `.rs`. +r[crate.module-def] 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 [_Module_][module] item in a referencing -source file, or by the name of the crate itself. Every source file is a +source file, or by the name of the crate itself. + +r[crate.inline-module] +Every source file is a module, but not every module needs its own source file: [module definitions][module] can be nested within one file. +r[crate.items] Each source file contains a sequence of zero or more [_Item_] definitions, and 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 +the compiler. + +r[crate.attributes] +The anonymous crate module can have additional attributes that apply to the crate as a whole. > **Note**: The file's contents may be preceded by a [shebang]. @@ -62,8 +77,13 @@ apply to the crate as a whole. ## Main Functions -A crate that contains a `main` [function] can be compiled to an executable. If a -`main` function is present, it must take no arguments, must not declare any +r[crate.main] + +r[crate.main.general] +A crate that contains a `main` [function] can be compiled to an executable. + +r[crate.main.restriction] +If a `main` function is present, it must take no arguments, must not declare any [trait or lifetime bounds], must not have any [where clauses], and its return type must implement the [`Termination`] trait. @@ -81,6 +101,7 @@ fn main() -> impl std::process::Termination { } ``` +r[crate.main.import] The `main` function may be an import, e.g. from an external crate or from the current one. ```rust @@ -105,12 +126,18 @@ use foo::bar as main; ### The `no_main` attribute +r[crate.no_main] + The *`no_main` [attribute]* may be applied at the crate level to disable emitting the `main` symbol for an executable binary. This is useful when some other object being linked to defines `main`. ## The `crate_name` attribute +r[crate.crate_name] + + +r[crate.crate_name.general] The *`crate_name` [attribute]* may be applied at the crate level to specify the name of the crate with the [_MetaNameValueStr_] syntax. @@ -118,6 +145,7 @@ name of the crate with the [_MetaNameValueStr_] syntax. #![crate_name = "mycrate"] ``` +r[crate.crate_name.restriction] The crate name must not be empty, and must only contain [Unicode alphanumeric] or `_` (U+005F) characters. From 347f3e2a506b12862b59f1c255d7d31854f16014 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Tue, 13 Aug 2024 15:05:25 -0400 Subject: [PATCH 2/3] Fix formatting of crates-and-source-files.md --- src/crates-and-source-files.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index 40538f09d..89a04bd1b 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -44,7 +44,7 @@ r[crate.module-def] 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 [_Module_][module] item in a referencing -source file, or by the name of the crate itself. +source file, or by the name of the crate itself. r[crate.inline-module] Every source file is a @@ -55,7 +55,7 @@ r[crate.items] Each source file contains a sequence of zero or more [_Item_] definitions, and may optionally begin with any number of [attributes] that apply to the containing module, most of which influence the behavior of -the compiler. +the compiler. r[crate.attributes] The anonymous crate module can have additional attributes that @@ -80,7 +80,7 @@ apply to the crate as a whole. r[crate.main] r[crate.main.general] -A crate that contains a `main` [function] can be compiled to an executable. +A crate that contains a `main` [function] can be compiled to an executable. r[crate.main.restriction] If a `main` function is present, it must take no arguments, must not declare any From 1f3675cc607ee1ef41c6ade0ec7926c76fda08df Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Wed, 21 Aug 2024 19:49:28 -0400 Subject: [PATCH 3/3] Remove double line break from crates-and-source-files.md --- src/crates-and-source-files.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/crates-and-source-files.md b/src/crates-and-source-files.md index 89a04bd1b..734ee3e98 100644 --- a/src/crates-and-source-files.md +++ b/src/crates-and-source-files.md @@ -136,7 +136,6 @@ other object being linked to defines `main`. r[crate.crate_name] - r[crate.crate_name.general] The *`crate_name` [attribute]* may be applied at the crate level to specify the name of the crate with the [_MetaNameValueStr_] syntax.