01.Introduction

Introduction

---

• Installation
  • rustup
  • cargo
  • C-Compiler
  • Installation For Linux/MacOS
  • Installation For Windows
  • Installation Profiles
• Post-Installation Checks
  • rustup docs
• Additional rustup Commands
• Hello World
  • Compiling Rust Code
• Hello Cargo
  • Main Commands
  • Check cargo Version
  • Creating A Project
  • Building A Project
    • Build And Run At Once
    • Check Pre-Build
    • Building For Release
  • Cargo As Convention

---

Installation

• Using rustup
  • Command-line tool for managing Rust versions
  • Installs Rust, Cargo, and additional developer tools

rustup

Settings	Value	Default Value
Home Directory	~/.rustup
Environment Variable	RUSTUP_HOME	~/.rustup

• RUSTUP_HOME can be used to customize installation

cargo

Settings	Value	Default Value
Home Directory	~/.cargo
Environment Variable	CARGO_HOME	~/.cargo

• CARGO_HOME can be used to customize installation
• Paths are added to:
  • ~/.profile
  • ~/.bash_profile
  • ~/.bashrc
  • Environment Variables

C-Compiler

• Need a C-Compiler & Linker
• Used to join compiled outputs into one file

Installation For Linux/MacOS

• For Linux, install gcc or clang
• build-essential => dpkg-dev, g++, gcc, libc6-dev, make

# GCC
# ---
# Check if already installed
gcc --version

# If not, install via build-essential
sudo apt-get install build-essential

# Clang
# -----
# Check if already installed
clang --version

# If not, search available versions
apt-cache search clang

# Install latest version available: In this case, v15
sudo apt-get install clang-15 --install-suggests

• For MacOS, install XCode's compiler

xcode-select --install

• Check if rustup is already installed

# Check if rustup is already installed
rustup --version

• If not, install rustup via curl
• This also bootstraps the installation of the Rust dev tools via rustup

# Install rustup via curl, then Rust dev tools
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

Installation For Windows

• For Windows, need to install MSVC Build Tools For Visual Studio 2013 or later
• It can be installed with Visual Studio Installer
  • Install Visual Studio
  • Choose Desktop Development with C++
  • Choose appropriate Windows SDK
  • To check the version of the compiler, call with no argument:
    • x64: C:\"Program Files"\"Microsoft Visual Studio"\2022\Community\VC\Tools\MSVC\<<version>>\bin\Hostx64\x64\cl.exe
    • x86: C:\"Program Files"\"Microsoft Visual Studio"\2022\Community\VC\Tools\MSVC\<<version>>\bin\Hostx64\x86\cl.exe
• Check if rustup is installed

# Check if rustup is already installed
rustup --version

• If not, download and run rustup-init.exe from rust-lang.org

Installation Profiles

Installation Profile	Included
Minimal	rustc,rust-std,cargo
Default (Recommended)	Minimal + rust-docs, rustfmt, clippy
Complete	Default + All components available through rustup: Every component ever included in the metadata This option should never be used except for maintainers

Post-Installation Checks

# Check the installed toolchain
rustup toolchain list

# List the installed components
rustup component list --installed

Component	Description
cargo	Package Manager / Build Tool
clippy	A collection of lints to catch common mistakes
rust-docs	All Rust Documentations installed locally for offline use: Access via rustup docs or rustup doc command
rust-std	Rust Standard Library
rustc	Rust Compiler
rustfmt	Rust Formatter to follow standard style guidelines

rustup docs

• Allows to access Rust Documentations offline
• There are multiple options available

Command	Docs For
rustup docs	Rust Documentation Index
--alloc	The Rust Core Allocation and Collections library
--book	The Rust Programming Book (The Book)
--cargo	The Cargo Book
--core	The Rust Core Library
--edition-guide	The Rust Edition Guide
--embedded-book	The Embedded Rust Book
--help	Prints help about rustup docs commands
--nomicon	The Rustonomicon: The Dark Arts of Advanced and Unsafe Rust Programming
--path	Print the path to the local offline documentations
--proc_macro	A support library for macro authors when defining new macros
--reference	The Rust Reference
--rust-by-example	A collection of runnable examples that illustrate various Rust concepts and standard libraries
--rustc	The Rust Compiler Book
--rustdoc	The rustdoc Book: Documentation Generation tool for Rust projects
--std	Standard library API documentation
--test	Library to support code for rustc's built-in unit-test and micro-benchmarking framework
--unstable-book	The Rust Unstable Book
--toolchain <toolchain>	Rust documentations specific to a Toolchain (The toolchain must be installed)

Additional rustup Commands

Command	Description
rustc --version	Check installed Rust Compiler version
rustup docs or rustup doc	Open local documentations index
rustup update	Update all installed rustup components
rustup self uninstall	Uninstall Rust and all its components

Hello World

• Create a hello-world project folder with the following structure

hello-world/
├── target/
└── src/
    └── main.rs

• Open main.rs in an editor and add the following codes to main.rs

/****************************************/
/* Print "Hello world!" to the console. */
/****************************************/

/// The entry-point of the program.
fn main() {
    println!();
    println!("Hello world!");
    println!();
}

// ON LINUX:
//      Compile: rustc src/main.rs -o target/main
//      Execute: ./target/main
// ON WINDOWS:
//      Compile: rustc src\main.rs -o target\main.exe
//      Execute: .\target\main.exe

• main() function is the entry-point in every executable Rust program
  • No parameters
  • No return values
• Rust requires curly brackets around all function bodies
  • Recommended style to place the opening curly bracket on the same line as the function declaration
  • Automatic formatter tool rustfmt is used with cargo
  • Rust style is to indent with 4 spaces, not tabs
• macroname!() is a macro
  • Functions and Macros are different in Rust
  • Macros do not always follow the same rules as Functions
  • E.g. println!() is a macro
• Most lines in Rust end with a semicolon (;), but not all of them (see expression vs statement)

Compiling Rust Code

• Rust is Ahead-Of-Time (AOT) compiled language
  • Produces a single executable file
  • Similar to C, C++, Go
  • Compiler: rustc
• On Windows, compiling also outputs a .pdb file for debugging info

# Compiling on Linux
rustc src/main.rs -o target/main

# Executing on Linux
./target/main

# Compiling on Windows
rustc src\main.rs -o target\main.exe

# Executing on Windows
.\target\main.exe

• NOTE: rustc alone is not enough for larger projects
  • We use cargo instead
  • cargo allows to better manage a larger project

Hello Cargo

• Cargo is the Build System and Package Manager for Rust
• Allows to manage projects
  • Build codes
  • Download dependencies
  • Build libraries
• It is better to start a project using cargo
  • The vast majority of Rust projects are built with cargo
• Cargo comes with Rust when installing via rustup
• Full documentation for cargo is available in the Cargo Book Online or Offline

rustup docs --cargo

Main Commands

• The commands are the same no matter which operating system

Command	Description
cargo new	Create a new project
cargo build	Compile the source codes in the current project (debug mode)
cargo build --release	Compile the source codes with optimizations (release mode)
cargo run	Build + Run the project (debug mode)
cargo run --release	Build + Run the project (release mode)
cargo check	Check compile status without compiling (debug mode)

• NOTE: Always use --release when building for final production
  • Can greatly improve the size of binary
  • Also adds additional optimizations

Check cargo Version

cargo --version

Creating A Project

cargo new hello-cargo

• Creates a new project directory: hello-cargo

hello-cargo/
├── .git/
├── .gitignore
├── Cargo.toml
└── src/
    └── main.rs

Folder or File	Description
.git	Default Version Control System (VCS) Not generated if already within a Git project Can override with --vcs flag
.gitignore	Default Version Control System (VCS) is Git Not generated if already within a Git project Can override with --vcs flag
Cargo.toml	Manage project configs and dependencies/crates
src/main.rs	The entrance of the program

• NOTE: Git-related files are not generated if already within an existing Git repository
• Cargo.toml can have multiple sections but the following are defaulted
  • [package]
    • Configure the project as a package
    • Also adds compiler info
      • name - Name of the Package
      • version - Version of the Package
      • edition - The Rust edition to use
    • See more keys and their definitions at Cargo Reference
    • See more details about Rust Editions at The Rust Edition Guide
  • [dependencies]
    • List of crates dependencies for the project
    • If none is listed, then the project will install no additional dependency crates

[package]
name = "hello-cargo"
version = "0.1.0"
edition = "2021"

[dependencies]

• All source codes should live in src
  • Except for non-source code files, which can be in top-level project directory:
    • README files
    • License information
    • Configuration files: Cargo.toml, Cargo.lock
    • Anything else not related to code
• Cargo helps organize projects
  • There is a place for everything
  • Everything is in its place
• It is possible to convert a manually-managed project to Cargo project
  • Move the project code into the src directory
  • Create an appropriate Cargo.toml file: Can be done by running cargo init

/*****************************************/
/* Print "Hello, world!" to the console. */
/*****************************************/

/// The entry-point of the program.
fn main() {
    println!();
    println!("Hello world!");
    println!();
}

// Check:               $ cargo check
// Build:               $ cargo build
// Build + Run:         $ cargo run
// Execute:             $ ./target/debug/hello-cargo
// Build Release:       $ cargo build --release
// Build + Run Release: $ cargo run --release
// Execute Release:     $ ./target/release/hello-cargo

Building A Project

• Simply cd into the project and run cargo build

cd hello-cargo
cargo build

• It builds from src folder
  • Default build is Debug Build dev [unoptimized + debuginfo]
  • Creates an executable file in target/debug
• First-time build also creates Cargo.lock
  • Keeps track of the exact versions of dependencies/crates in the project
  • Managed by Cargo: This file is automatically generated by Cargo
  • Never need to change this file manually: It is not intended for manual editing

Build And Run At Once

• We can run cargo run to build and run at once
• Convenience for cargo build + run binaries

cd hello-cargo
cargo run

• NOTE: Cargo will only rebuild if there are diff changes detected
• NOTE: We can also use cargo run --release for the release option

Check Pre-Build

• cargo check allows to check if a project can build without generating the binaries
• Much faster than cargo build
  • Skips the step of producing an executable
  • Still generates target but not the executable file
  • Helpful for multiple periodical compiling-checks when writing code (e.g. watching for changes, debugging errors)

cd hello-cargo
cargo check

Building For Release

• Default build is Debug Build (dev [unoptimized + debuginfo])
• To build for release, we use the --release option

cd hello-cargo
cargo build --release

• Compiles with optimizations: Binary size is much smaller
• Creates an executable file in target/release
• Makes Rust code run faster
• But longer build-time is needed
• Only use this for building the final program

Cargo As Convention

• Cargo is invaluable for large and complex projects
• Additional tooling for project management
• We can use cargo build on any project made with cargo