rust/doc/tutorial/mod.md

Modules and crates

The Rust namespace is divided in modules. Each source file starts with its own, empty module.

Local modules

The mod keyword can be used to open a new, local module. In the example below, chicken lives in the module farm, so, unless you explicitly import it, you must refer to it by its long name, farm::chicken.

mod farm {
    fn chicken() -> str { "cluck cluck" }
    fn cow() -> str { "mooo" }
}
fn main() {
    log_err farm::chicken();
}

Modules can be nested to arbitrary depth.

Crates

The unit of independent compilation in Rust is the crate. Libraries tend to be packaged as crates, and your own programs may consist of one or more crates.

When compiling a single .rs file, the file acts as the whole crate. You can compile it with the --lib compiler switch to create a shared library, or without, provided that your file contains a fn main somewhere, to create an executable.

It is also possible to include multiple files in a crate. For this purpose, you create a .rc crate file, which references any number of .rs code files. A crate file could look like this:

#[link(name = "farm", vers = "2.5", author = "mjh")];
mod cow;
mod chicken;
mod horse;

Compiling this file will cause rustc to look for files named cow.rs, chicken.rs, horse.rs in the same directory as the .rc file, compile them all together, and, depending on the presence of the --lib switch, output a shared library or an executable.

The #[link(...)] part provides meta information about the module, which other crates can use to load the right module. More about that in a moment.

To have a nested directory structure for your source files, you can nest mods in your .rc file:

mod poultry {
    mod chicken;
    mod turkey;
}

The compiler will now look for poultry/chicken.rs and poultry/turkey.rs, and export their content in poultry::chicken and poultry::turkey. You can also provide a poultry.rs to add content to the poultry module itself.

Using other crates

Having compiled a crate with --lib, you can use it in another crate with a use directive. We've already seen use std in several of the examples, which loads in the standard library.

use directives can appear in a crate file, or at the top level of a single-file .rs crate. They will cause the compiler to search its library search path (which you can extend with -L switch) for a Rust crate library with the right name. This name is deduced from the crate name in a platform-dependent way. The farm library will be called farm.dll on Windows, libfarm.so on Linux, and libfarm.dylib on OS X.

It is possible to provide more specific information when using an external crate.

use myfarm (name = "farm", vers = "2.7");

When a comma-separated list of name/value pairs is given after use, these are matched against the attributes provided in the link attribute of the crate file, and a crate is only used when the two match. A name value can be given to override the name used to search for the crate. So the above would import the farm crate under the local name myfarm.

Our example crate declared this set of link attributes:

#[link(name = "farm", vers = "2.5", author = "mjh")];

The version does not match the one provided in the use directive, so unless the compiler can find another crate with the right version somewhere, it will complain that no matching crate was found.

A minimal example

Now for something that you can actually compile yourself. We have these two files:

// mylib.rs
#[link(name = "mylib", vers = "1.0")];
fn world() -> str { "world" }

// main.rs
use mylib;
fn main() { log_err "hello " + mylib::world(); }

Now compile and run like this (adjust to your platform if necessary):

> rustc --lib mylib.rs
> rustc main.rs -L .
> ./main
"hello world"

Importing

When using identifiers from other modules, it can get tiresome to qualify them with the full module path every time (especially when that path is several modules deep). Rust allows you to import identifiers at the top of a file or module.

use std;
import std::io::println;
fn main() {
    println("that was easy");
}

It is also possible to import just the name of a module (import std::io;, then use io::println), import all identifiers exported by a given module (import std::io::*), or to import a specific set of identifiers (import std::math::{min, max, pi}).

It is also possible to rename an identifier when importing, using the = operator:

import prnt = std::io::println;

Exporting

By default, a module exports everything that it defines. This can be restricted with export directives at the top of the module or file.

mod enc {
    export encrypt, decrypt;
    const super_secret_number: int = 10;
    fn encrypt(n: int) { n + super_secret_number }
    fn decrypt(n: int) { n - super_secret_number }
}

This defines a rock-solid encryption algorithm. Code outside of the module can refer to the enc::encrypt and enc::decrypt identifiers just fine, but it does not have access to enc::syper_secret_number.

Namespaces

Rust uses three different namespaces. One for modules, one for types, and one for values. This means that this code is valid:

mod buffalo {
    type buffalo = int;
    fn buffalo(buffalo: buffalo) -> buffalo { buffalo }
}
fn main() {
    let buffalo: buffalo::buffalo = 1;
    buffalo::buffalo(buffalo::buffalo(buffalo));
}

You don't want to write things like that, but it is very practical to not have to worry about name clashes between types, values, and modules. This allows us to have a module std::str, for example, even though str is a built-in type name.

Resolution

The resolution process in Rust simply goes up the chain of contexts, looking for the name in each context. Nested functions and modules create new contexts inside their parent function or module. A file that's part of a bigger crate will have that crate's context as parent context.

Identifiers can shadow each others. In this program, x is of type int:

type x = str;
fn main() {
    type x = int;
    let x: int;
}

An import directive will only import into the namespaces for which identifiers are actually found. Consider this example:

type bar = uint;
mod foo { fn bar() {} }
mod baz {
    import foo::bar;
    const x: bar = 20u;
}

When resolving the type name bar in the const definition, the resolver will first look at the module context for baz. This has an import named bar, but that's a function, not a type, So it continues to the top level and finds a type named bar defined there.

Normally, multiple definitions of the same identifier in a scope are disallowed. Local variables defined with let are an exception to this—multiple let directives can redefine the same variable in a single scope. When resolving the name of such a variable, the most recent definition is used.

fn main() {
    let x = 10;
    let x = x + 10;
    assert x == 20;
}

This makes it possible to rebind a variable without actually mutating it, which is mostly useful for destructuring (which can rebind, but not assign).