.RS File Format – File structure

Crates and the module tree

A crate is the unit of compilation and linking. Each compilation reads one crate in source form and produces one crate in binary form: an executable or a library. A crate holds a tree of nested modules. The top of the tree is an anonymous module, and every item in the crate has a path that shows where it sits in the tree.

• Every source file is a module, but a module does not need its own file: a mod name { … } block nests a module inside a file.
• A file’s name and position in the tree are decided from outside it: by a mod declaration in another file, or by the crate name for the root file.
• A source file holds zero or more items, and may begin with inner attributes that apply to its module.

Crate:
    InnerAttribute*
    Item*

The crate type chooses the output. It is set with --crate-type on the command line or #![crate_type = "…"] in the root file.

Encoding and input processing

Before tokens are read, the compiler applies these steps to the file (Reference: Input format).

1. UTF-8. The file is read as UTF-8. Anything else is a compile-time error.
2. Byte order mark. A leading U+FEFF is removed if present.
3. Line endings. Each CR LF pair (U+000D U+000A) is replaced by a single LF. A lone CR is left in place and counts as white space, but it is rejected inside string literals and doc comments. The replacement happens once: CR CR LF LF becomes CR LF LF, not LF LF.
4. Shebang removal. A shebang line is removed if present.
5. Tokenisation. The remaining characters are split into the tokens described on the Lexical structure page.

The include! macro applies the byte order mark, line ending and (in item position only) shebang steps to the file it includes. include_str! and include_bytes! apply none of them.

Shebang line

A shebang is an optional first line that tells a Unix-like system which interpreter runs the file. It starts with #! at the very start of the file, or straight after a byte order mark, and runs to the first line feed or the end of the file (Reference: Shebang).

If the #! is followed by [, ignoring any white space and comments in between, the line is not a shebang. It is an inner attribute instead, such as #![allow(unused)].

#!/usr/bin/env rustx

fn main() {
    println!("Hello!");
}

Inner attributes

Attributes written #![…] at the top of a file, after any shebang, apply to the enclosing module. In the root file of a crate they apply to the crate as a whole. Some apply only there, such as crate_name, crate_type, no_std, no_main and recursion_limit. The Attributes page lists them all.

#![crate_name = "projx"]        // the crate's name
#![crate_type = "lib"]          // the kind of output
#![warn(non_camel_case_types)]  // a lint level; valid in any module

Doc comments written //! or /*! … */ are inner attributes too: they are shorthand for #![doc = "…"] and document the enclosing module.

Editions

Every crate is compiled in one edition: 2015, 2018, 2021 or 2024. The edition is not recorded in the .rs file. It is given to the compiler with --edition; without the option rustc uses 2015. Cargo passes the value of the edition key in Cargo.toml. The edition can change how the same text is tokenised and parsed, for example whether async is a keyword.

How mod maps to files

Module:
      unsafe? mod IDENTIFIER ;
    | unsafe? mod IDENTIFIER { InnerAttribute* Item* }

A module with no body is loaded from a file. Without a path attribute the file’s path follows the module’s path: ancestor modules are folders, and the module’s contents are in a file named after it plus .rs (Reference: Modules). The older form puts the module in mod.rs inside a folder named after it. Having both for one module is an error.

Before rustc 1.30, mod.rs was the only way to give a module child modules in their own files.

Module names read from the file system must be ASCII, unless a path attribute gives the file. The unsafe keyword before mod is accepted by the parser but rejected afterwards, so that macros can consume it.

mod inline {
    #[path = "other.rs"]
    mod inner;
}

The main function

A crate with a main function can be built as an executable. main must take no arguments, have no trait or lifetime bounds and no where clause, and its return type must implement std::process::Termination (Reference: Crates and source files). The standard library implements Termination for (), !, Infallible, ExitCode and Result<T, E> where T: Termination and E: Debug. The main function may be an import, such as use foo::bar as main;.

#![no_main] stops the compiler emitting a main symbol, which is useful when another linked object defines it.

The Cargo package layout

Cargo is the standard build tool. Its layout is a set of conventions, not part of the language. A package has a Cargo.toml manifest, and a Cargo.lock file that records exact dependency versions, in its root.

Cargo.toml
Cargo.lock
build.rs                     (optional build script)
src/
    lib.rs                   the library crate's root
    main.rs                  the default binary crate's root
    bin/
        tool.rs              another binary, named tool
        other/main.rs        a binary split over several files
benches/large-input.rs       a benchmark target
examples/simple.rs           an example target
tests/integration.rs         an integration test target

• Each file directly in src/bin, benches, examples or tests is a crate of its own. For a target spread over several files, make a folder with a main.rs in it; the target takes the folder’s name.
• Target names use kebab-case and module names use snake_case. Crate names may not contain hyphens, so Cargo replaces - with _ in a package name when it makes the crate name.
• The edition key and the dependencies are in Cargo.toml. A .rs file does not say which crates it may use; in edition 2018 and later, a dependency’s name can be used directly in paths.

build.rs

A build.rs file in the package root is a Rust program that Cargo compiles and runs just before building the package. It is typically used to build bundled C libraries, find system libraries or generate code. Its current directory is the package root, and a non-zero exit status stops the build.

It talks to Cargo by printing lines of the form cargo::KEY=VALUE to standard output (the cargo:: form needs Rust 1.77; older versions use cargo:). Other lines are ignored.

Generated files must go in the folder named by the OUT_DIR environment variable, and nowhere else. With no rerun-if directive, Cargo re-runs the script whenever any file in the package changes.

// build.rs
fn main() {
    println!("cargo::rerun-if-changed=src/hello.c");
    println!("cargo::rustc-link-lib=z");
}