Rust modules

Modules are rust libraries.
The std::prelude module is included in the scope of every program.

Documentation

official docs	https://doc.rust-lang.org/reference/items/modules.html
cargo book: package layout	https://doc.rust-lang.org/cargo/guide/project-layout.html

Tutorials

rust module system

https://www.sheshbabu.com/posts/rust-module-system/

Examples

The core idea is that main.rs/lib.rs must directly/indirectly import all paths.

• crate is the root namespace of the crate
• mod allows access to a namespace, using namespace prefix, for modules in same-directory
• use merges a namespace (or elements from it) into the current namespace
• pub mod exposes module externally
• super, within use/mod refers to the parent scope

sample-1: (mod) use module from namespace

src/
  main.rs
  house.rs

src/main.rs

// main.rs

mod house;

fn main() {
    println!("{}", house::house_name());
}

house.rs / house/mod.rs

// house.rs  /  house/mod.rs

pub fn house_name() -> String {
    String:from("hi")
}

sample-2 (mod) use file from submodule

In order to use street::lamps::* from main.rs,
we must publish lamps from street.

src/
  main.rs
  street/
    mod.rs
    lamps.rs

main.rs

// main.rs

mod street;

fn main() {
    printlnt("{}", street::lamps::brightness());
}

street/mod.rs

// street/mod.rs

pub mod lamps;

street/lamps.rs

// street/lamps.rs

pub fn brightness() -> isize {
    100
}

sample-3 (use) use file from submodule

In order to use street::lamps::* from main.rs,
we must publish lamps from street.

src/
  street/
    mod.rs
    lamps.rs
  main.rs

src/main.rs

mod street;
use street::lamps::*;

fn main() {
    println!("{}", brightness());
}

src/street/mod.rs

// src/street/mod.rs

pub mod lamps;

src/street/lamp.rs

// src/street/lamp.rs

pub fn brightness() -> isize {
    100
}

sample-4 use lib.rs from main.rs

When building executables, it's customary for most of the business-logic to live in lib.rs,
with a tiny skeleton program in main.rs.

Code from lib.rs will be imported from your project-name's namespace.

// main.rs

use my_project;  // code from `lib.rs`

fn main() {
    my_project::some_function();
}

Entrypoints

For modules to be compiled, they must be used (however indirectly) from their crate-root (build target).
By default these are:

• src/main.rs for executables
• src/lib.rs for libraries (imported as the package-name)

See rust anatomy for more details.

Imports

• use merge namespace into current (ex. use foo; myfn();)
• use as lets you alias a namespace
• mod enables you to access from namespace (ex. mod foo; foo::myfn();)

use (merge with current namespace)

use std::io;                      // merges objects from namespace into your own
use std::io::*;                   //
use std::fs::File;                // import 'File' only into current namespace
use std::fs::{File, DirBuilder};  // import multiple types/functions into current namespace
use std::fs as fs                 // within this namespace, refer to 'std::fs' as 'fs'

std::io::stdin()                  // you also can access objects directly from their namespace without `use`

mod enables access to submodules, 1-level deep, from current module.

// expose ./foo.rs or ./foo/mod.rs from current module
pub mod foo;

Access Control

By default, a module's code is public to itself and it's children,
but private to it's parents and/or callers.
The pub keyword exposes a module/function.

• parents modules can expose access to their children with pub mod ${foo}
• child modules can access their parents without importing them using super::
• child modules can use absolute paths to symbols, from the crate:: namespace
• imports are private by default, unless you import using pub use some::module

See rust access control for more details.