src/doc/reference/src/crates-and-source-files.md

   1 # Crates and source files
   2
   3 > **<sup>Syntax</sup>**\
   4 > _Crate_ :\
   5 > &nbsp;&nbsp; UTF8BOM<sup>?</sup>\
   6 > &nbsp;&nbsp; SHEBANG<sup>?</sup>\
   7 > &nbsp;&nbsp; [_InnerAttribute_]<sup>\*</sup>\
   8 > &nbsp;&nbsp; [_Item_]<sup>\*</sup>
   9
  10 > **<sup>Lexer</sup>**\
  11 > UTF8BOM : `\uFEFF`\
  12 > SHEBANG : `#!` ~[`[` `\n`] ~`\n`<sup>\*</sup>
  13
  14
  15 > Note: Although Rust, like any other language, can be implemented by an
  16 > interpreter as well as a compiler, the only existing implementation is a
  17 > compiler, and the language has always been designed to be compiled. For these
  18 > reasons, this section assumes a compiler.
  19
  20 Rust's semantics obey a *phase distinction* between compile-time and
  21 run-time.[^phase-distinction] Semantic rules that have a *static
  22 interpretation* govern the success or failure of compilation, while
  23 semantic rules that have a *dynamic interpretation* govern the behavior of the
  24 program at run-time.
  25
  26 The compilation model centers on artifacts called _crates_. Each compilation
  27 processes a single crate in source form, and if successful, produces a single
  28 crate in binary form: either an executable or some sort of
  29 library.[^cratesourcefile]
  30
  31 A _crate_ is a unit of compilation and linking, as well as versioning,
  32 distribution, and runtime loading. A crate contains a _tree_ of nested
  33 [module] scopes. The top level of this tree is a module that is
  34 anonymous (from the point of view of paths within the module) and any item
  35 within a crate has a canonical [module path] denoting its location
  36 within the crate's module tree.
  37
  38 The Rust compiler is always invoked with a single source file as input, and
  39 always produces a single output crate. The processing of that source file may
  40 result in other source files being loaded as modules. Source files have the
  41 extension `.rs`.
  42
  43 A Rust source file describes a module, the name and location of which &mdash;
  44 in the module tree of the current crate &mdash; are defined from outside the
  45 source file: either by an explicit [_Module_][module] item in a referencing
  46 source file, or by the name of the crate itself. Every source file is a
  47 module, but not every module needs its own source file: [module
  48 definitions][module] can be nested within one file.
  49
  50 Each source file contains a sequence of zero or more [_Item_] definitions, and
  51 may optionally begin with any number of [attributes]
  52 that apply to the containing module, most of which influence the behavior of
  53 the compiler. The anonymous crate module can have additional attributes that
  54 apply to the crate as a whole.
  55
  56 ```rust
  57 // Specify the crate name.
  58 #![crate_name = "projx"]
  59
  60 // Specify the type of output artifact.
  61 #![crate_type = "lib"]
  62
  63 // Turn on a warning.
  64 // This can be done in any module, not just the anonymous crate module.
  65 #![warn(non_camel_case_types)]
  66 ```
  67
  68 The optional [_UTF8 byte order mark_] (UTF8BOM production) indicates that the
  69 file is encoded in UTF8. It can only occur at the beginning of the file and
  70 is ignored by the compiler.
  71
  72 A source file can have a [_shebang_] (SHEBANG production), which indicates
  73 to the operating system what program to use to execute this file. It serves
  74 essentially to treat the source file as an executable script. The shebang
  75 can only occur at the beginning of the file (but after the optional
  76 _UTF8BOM_). It is ignored by the compiler. For example:
  77
  78 <!-- ignore: tests don't like shebang -->
  79 ```rust,ignore
  80 #!/usr/bin/env rustx
  81
  82 fn main() {
  83     println!("Hello!");
  84 }
  85 ```
  86
  87 ## Preludes and `no_std`
  88
  89 All crates have a *prelude* that automatically inserts names from a specific
  90 module, the *prelude module*, into scope of each [module] and an [`extern
  91 crate`] into the crate root module. By default, the *standard prelude* is used.
  92 The linked crate is [`std`] and the prelude module is [`std::prelude::v1`].
  93
  94 The prelude can be changed to the *core prelude* by using the `no_std`
  95 [attribute] on the root crate module. The linked crate is [`core`] and the
  96 prelude module is [`core::prelude::v1`]. Using the core prelude over the
  97 standard prelude is useful when either the crate is targeting a platform that
  98 does not support the standard library or is purposefully not using the
  99 capabilities of the standard library. Those capabilities are mainly dynamic
 100 memory allocation (e.g. `Box` and `Vec`) and file and network capabilities (e.g.
 101 `std::fs` and `std::io`).
 102
 103 <div class="warning">
 104
 105 Warning: Using `no_std` does not prevent the standard library from being linked
 106 in. It is still valid to put `extern crate std;` into the crate and dependencies
 107 can also link it in.
 108
 109 </div>
 110
 111 ## Main Functions
 112
 113 A crate that contains a `main` [function] can be compiled to an executable. If a
 114 `main` function is present, it must take no arguments, must not declare any
 115 [trait or lifetime bounds], must not have any [where clauses], and its return
 116 type must  be one of the following:
 117
 118 * `()`
 119 * `Result<(), E> where E: Error`
 120 <!-- * `!` -->
 121 <!-- * Result<!, E> where E: Error` -->
 122
 123 > Note: The implementation of which return types are allowed is determined by
 124 > the unstable [`Termination`] trait.
 125
 126 <!-- If the previous section needs updating (from "must take no arguments"
 127   onwards, also update it in the testing.md file -->
 128
 129 ### The `no_main` attribute
 130
 131 The *`no_main` [attribute]* may be applied at the crate level to disable
 132 emitting the `main` symbol for an executable binary. This is useful when some
 133 other object being linked to defines `main`.
 134
 135 ## The `crate_name` attribute
 136
 137 The *`crate_name` [attribute]* may be applied at the crate level to specify the
 138 name of the crate with the [_MetaNameValueStr_] syntax.
 139
 140 ```rust
 141 #![crate_name = "mycrate"]
 142 ```
 143
 144 The crate name must not be empty, and must only contain [Unicode alphanumeric]
 145 or `-` (U+002D) characters.
 146
 147 [^phase-distinction]: This distinction would also exist in an interpreter.
 148     Static checks like syntactic analysis, type checking, and lints should
 149     happen before the program is executed regardless of when it is executed.
 150
 151 [^cratesourcefile]: A crate is somewhat analogous to an *assembly* in the
 152     ECMA-335 CLI model, a *library* in the SML/NJ Compilation Manager, a *unit*
 153     in the Owens and Flatt module system, or a *configuration* in Mesa.
 154
 155 [Unicode alphanumeric]: ../std/primitive.char.html#method.is_alphanumeric
 156 [_InnerAttribute_]: attributes.md
 157 [_Item_]: items.md
 158 [_MetaNameValueStr_]: attributes.md#meta-item-attribute-syntax
 159 [_shebang_]: https://en.wikipedia.org/wiki/Shebang_(Unix)
 160 [_utf8 byte order mark_]: https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8
 161 [`Termination`]: ../std/process/trait.Termination.html
 162 [`core`]: ../core/index.html
 163 [`core::prelude::v1`]: ../core/prelude/index.html
 164 [`extern crate`]: items/extern-crates.md
 165 [`std`]: ../std/index.html
 166 [`std::prelude::v1`]: ../std/prelude/index.html
 167 [attribute]: attributes.md
 168 [attributes]: attributes.md
 169 [function]: items/functions.md
 170 [module]: items/modules.md
 171 [module path]: paths.md
 172 [trait or lifetime bounds]: trait-bounds.md
 173 [where clauses]: items/generics.md#where-clauses