Rust modules

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

Documentation

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 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

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

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
}

Entrypoints

For modules to be compiled, they must be used (however indirectly) from:

• src/main.rs for executables
• src/lib.rs for libraries

Naming/Paths

Module names govern where they can be found within the filesystem.
Module locations are based on where they are defined

# from the rust book:
backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

The module foo's code could be

• src/foo.rs
• src/foo/mod.rs

Imports

• use merge namespace into current (ex. use foo; myfn();)
• 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

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

mod (access namespace)

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.

pub mod house {
    pub mod livingroom {
        // ...
    }
    mod bedroom {
        // ...
    }
}