Rust Tutorial : Modules
from tutorialspoint.com

Terms & Descriptions
a logical group of code is called a module
multiple modules are compiled into a unit called crate
Rust programs may contain a binary crate or a library crate
a binary crate is an executable project that has a main() method
library crate is a group of components that can be reused in other projects
a library crate does not have an entry point : main() method
the Cargo tool is used to manage crates in Rust
modules are similar to namespaces in other programming languages
third-party crates can be downloaded using cargo from crates.io
  • crate - is a compilation unit in Rust
    Crate is compiled to binary or library
  • cargo - the official Rust package management tool for crates
  • module - logically groups code within a crate
  • crates.io - the official Rust package registry
syntax 
//public module
pub mod a_public_module {
   pub fn a_public_function() {
      //public function
   }
   fn a_private_function() {
      //private function
   }
}
//private module
mod a_private_module {
   fn a_private_function() {
   }
}
modules can be public or private
components in a private module cannot be accessed by other modules
modules in Rust are private by default
functions in a public module can be accessed by other modules
modules should be prefixed with pub keyword to make them public
functions within a public module must also be made public
Defining a Module
example defines a public module − movies
module contains a function play() that accepts a parameter and prints its value 
pub mod movies {
   pub fn play(name:String) {
      println!("Playing movie {}",name);
   }
}
fn main(){
   movies::play("Herold and Kumar".to_string());
}
Use Keyword
the use keyword used to import a public module
syntax 
use public_module_name::function_name;
Nested Modules
modules can also be nested
the comedy module is nested within the english module which is further nested in the movies module
the example given below defines a function play inside the movies/english/comedy module 
pub mod movies {
   pub mod english {
      pub mod comedy {
         pub fn play(name:String) {
            println!("Playing comedy movie {}",name);
         }
      }
   }
}
use movies::english::comedy::play; 
// importing a public module

fn main() {
   // short path syntax
   play("Herold and Kumar".to_string());
   play("The Hangover".to_string());

   //full path syntax
   movies::english::comedy::play("Airplane!".to_string());
}
output 
Playing comedy movie Herold and Kumar
Playing comedy movie The Hangover
Playing comedy movie Airplane!
Crate Example (step-by-step)
  1. Create Project folder
  2. Edit the Cargo.toml file to add project metadata
  3. Edit the lib.rs file
  4. Edit the movies.rs file
  5. Build the library crate
  6. Create a test application
  7. Add the following in the Cargo.toml file
  8. Add the following to main.rs file
  9. Use of cargo build and cargo run
1 : Create Project folder
create a library crate named movie_lib which contains a module movies
to build the movie_lib library crate use the tool cargo

create a folder movie-app followed by a sub-folder movie-lib
after the folder and sub-folder are created, create an src folder and a Cargo.toml file in movie-lib directory
the source code should go in the src folder
create the files lib.rs and movies.rs in the src folder
the Cargo.toml file will contain the metadata of the project like version number, author name, etc.

movie-app
   movie-lib/
      Cargo.toml
      src/
         lib.rs
         movies.rs
2 : Edit the Cargo.toml file to add project metadata
add the following to Cargo.html 
[package]
name = "movies_lib"
version = "0.1.0"
authors = ["Mohtashim"]
3 : Edit the lib.rs file
add the module definition to lib.rs
creates a public module 
pub mod movies;
4 : Edit the movies.rs file
movies.rs will define all functions for the movies module
define a function play() that accepts a parameter and prints it to the console 
pub fn play(name:String){
   println!("Playing movie {} :movies-app",name);
}
5 : Build the library crate
build app using the cargo build command to verify if the library crate is structured properly
from the project root, the movie-app folder, use the command cargo build
D:\Rust\movie-lib> cargo build
   Compiling movies_lib v0.1.0 (file:///D:/Rust/movie-lib)
   Finished dev [unoptimized + debuginfo] target(s) in 0.67s
6 : Create a test application
create another folder movie-lib-test in the movie-app folder followed by a Cargo.toml file and the src folder
this project should have main method as this is a binary crate
will consume the library crate created previously
create a main.rs file in the src folder
folder structure 
movie-app
   movie-lib 
   // already completed

   movie-lib-test/
      Cargo.toml
      src/
         main.rs
7 : Add the following in the Cargo.toml file
the path to the library folder is set as dependencies 
[package]
name = "test_for_movie_lib"
version = "0.1.0"
authors = ["Mohtashim"]

[dependencies]
movies_lib = { path = "../movie-lib" }
movie-lib project contains
  • lib.rs
  • movies.rs
  • cargo.toml

movie-lib-test project contains

  • main.rs
  • cargo.toml
8 : Add the following to main.rs file
code imports an external package called movies_lib
check the Cargo.toml of current project to verify the crate name 
extern crate movies_lib;
use movies_lib::movies::play;
fn main() {
   println!("inside main of test ");
   play("Tutorialspoint".to_string())
}
9 : Use of cargo build and cargo run
use the cargo build and cargo run commands from the console
from the project root, the movie-app-test folder, use the command cargo build
then the command cargo run
index