From 08e8bf2c0f1740b6a80cd7c36eda87f9454d2abe Mon Sep 17 00:00:00 2001 From: Jackson Hoffart Date: Mon, 25 Nov 2024 10:53:50 +0100 Subject: [PATCH 1/6] gains chapter 7 on crates and modules --- ...jects_with_packages_crates_and_modules.qmd | 108 ++++++++++++++++-- 1 file changed, 96 insertions(+), 12 deletions(-) diff --git a/slides/07-managing_growing_projects_with_packages_crates_and_modules.qmd b/slides/07-managing_growing_projects_with_packages_crates_and_modules.qmd index 8bec82b..2e2c726 100644 --- a/slides/07-managing_growing_projects_with_packages_crates_and_modules.qmd +++ b/slides/07-managing_growing_projects_with_packages_crates_and_modules.qmd @@ -5,27 +5,111 @@ title: "7. Managing Growing Projects with Packages, Crates, and Modules" # Learning objectives +By the end of this session, you should be able to: + ::: nonincremental -- THESE ARE NICE TO HAVE BUT NOT ABSOLUTELY NECESSARY +- Understand and use Rust's module system (`mod`, `pub`, `use`). +- Differentiate between packages, crates, and modules. +- Implement Cargo workspaces for multi-crate projects. +- Apply best practices for managing and organizing Rust projects. ::: ::: notes -- You can add notes on each slide with blocks like this! -- Load a deck in the browser and type "s" to see these notes. +Encourage questions about any points that feel unclear. ::: -# SLIDE SECTION +# Overview of Packages, Crates, and Modules + +## Key Concepts + +- **Package**: A bundle of one or more crates, defined by a `Cargo.toml` file. +- **Crate**: A compilation unit in Rust (binary or library). +- **Module**: A way to organize code and control scope and visibility. +- **Workspace**: A collection of interrelated packages managed together. + +# Creating and Using Packages + +## Setting Up a Package + +```console +$ cargo new my_project +$ cd my_project +``` + +- Creates a new package with a `Cargo.toml` and a default binary crate. +- Binary crate root: `src/main.rs`. +- To create a library crate, add a `src/lib.rs`. + +## Example `Cargo.toml` +``` toml +[package] +name = "my_project" +version = "0.1.0" +edition = "2021" + +[dependencies] +rand = "0.8.5" +``` + +# Working with Modules +## Accessing Module Items +``` rust +crate::front_of_house::hosting::add_to_waitlist(); +``` +- Use absolute paths starting with crate + +``` rust +front_of_house::hosting::add_to_waitlist(); +``` +- or, use relative paths starting with the module name + +## Controlling Visibility +``` rust +pub mod front_of_house { + pub mod hosting { + pub fn add_to_waitlist() {} + } +} +``` +- By default, items are private +- Use `pub` to make modules, functions, and fields accessible + +# Using `use` for Convenience +## Simplify Paths +``` rust +use crate::front_of_house::hosting; + +hosting::add_to_waitlist(); +``` +- Use use to shorten paths. +- Works within the scope it's defined. -## SLIDE +## Re-exporting with `pub use` +``` rust +pub use crate::front_of_house::hosting; -- DENOTE MAJOR SECTIONS WITH `# TITLE` (eg `# Installation`) -- ADD INDIVIDUAL SLIDES WITH `##` (eg `## rustup on Linux/macOS`) -- KEEP THEM RELATIVELY SLIDE-LIKE; THESE ARE NOTES, NOT THE BOOK ITSELF. +hosting::add_to_waitlist(); +``` +- Makes items available for external users. -## SLIDE +# Organizing Modules Across Files +## Splitting Modules +- Define a module in `src/lib.rs`: +``` rust +mod front_of_house; +``` +- Create `src/front_of_house.rs`: +``` rust +pub mod hosting { + pub fn add_to_waitlist() {} +} +``` -# SLIDE SECTION +- Nest submodules in `src/front_of_house/hosting.rs`. -## SLIDE +# Summary +- Rust's module system (`mod`, `pub`, `use`) is powerful for organizing code. +- Packages bundle functionality, crates define scope, and modules control visibility. +- Cargo workspaces help manage complex projects with multiple packages. -## SLIDE +Next steps: Practice by creating a workspace with two crates and exploring the module system further! From d42a8e8551edd8251f6f6980480671003e56e852 Mon Sep 17 00:00:00 2001 From: Jackson Hoffart Date: Mon, 25 Nov 2024 10:53:56 +0100 Subject: [PATCH 2/6] gains chapter 14 on cargo and crates.io --- slides/14-more_about_cargo_and_cratesio.qmd | 142 +++++++++++++++++--- 1 file changed, 125 insertions(+), 17 deletions(-) diff --git a/slides/14-more_about_cargo_and_cratesio.qmd b/slides/14-more_about_cargo_and_cratesio.qmd index 68dc393..864afe7 100644 --- a/slides/14-more_about_cargo_and_cratesio.qmd +++ b/slides/14-more_about_cargo_and_cratesio.qmd @@ -3,29 +3,137 @@ engine: knitr title: "14. More about Cargo and Crates.io" --- -# Learning objectives +# Learning Objectives +- Learn more about Cargo's advanced features: + - Customizing builds with release profiles. + - Publishing libraries to crates.io. + - Managing multi-crate projects with workspaces. + - Installing binaries using Cargo. + - Extending Cargo with custom commands. -::: nonincremental -- THESE ARE NICE TO HAVE BUT NOT ABSOLUTELY NECESSARY -::: +# Customizing Builds with Release Profiles -::: notes -- You can add notes on each slide with blocks like this! -- Load a deck in the browser and type "s" to see these notes. -::: +## Release Profiles +- **Profiles**: Predefined configurations for building code. + - `dev`: For development (`cargo build`). + - `release`: For production (`cargo build --release`). -# SLIDE SECTION +### Configuration in `Cargo.toml` +```toml +[profile.dev] +opt-level = 0 -## SLIDE +[profile.release] +opt-level = 3 +``` +- opt-level: Optimization levels (0-3). + - Development: Minimize build time. + - Production: Maximize runtime performance. -- DENOTE MAJOR SECTIONS WITH `# TITLE` (eg `# Installation`) -- ADD INDIVIDUAL SLIDES WITH `##` (eg `## rustup on Linux/macOS`) -- KEEP THEM RELATIVELY SLIDE-LIKE; THESE ARE NOTES, NOT THE BOOK ITSELF. +# Publishing a Crate to Crates.io +## Steps to Publish +1. Create an Account: Sign up at [crates.io](https://crates.io/). +2. Retrieve API Token: Use `cargo login` to store it locally. +3. Add Metadata in `Cargo.toml`: +``` toml +[package] +name = "my_crate" +description = "A brief description" +license = "MIT OR Apache-2.0" +``` +4. Run Publish: `cargo publish`. -## SLIDE +## Important Notes +- Published versions are permanent. +- You can "yank" a version to prevent new dependencies but retain existing ones. -# SLIDE SECTION +# Writing Documentation for Crates +## Documentation Comments +- Use `///` for documentation comments. +- Supports Markdown formatting. -## SLIDE +## Example +``` rust +/// Adds one to the input number. +/// +/// # Examples +/// +/// ``` +/// let result = my_crate::add_one(1); +/// assert_eq!(result, 2); +/// ``` +pub fn add_one(x: i32) -> i32 { + x + 1 +} +``` -## SLIDE +- Run `cargo doc --open` to generate HTML documentation +- Bonus: Examples in comments are tested with `cargo test` + +# Organizing Large Projects with Workspaces +## What is a Workspace? +- A workspace groups multiple crates. +- Shared: + - `Cargo.lock` (dependency versions). + - `target` directory (build artifacts). + +## Workspace Configuration +``` toml +[workspace] +members = ["crate1", "crate2"] +``` +Benefits: +- Simplifies management of interdependent crates. +- Avoids redundant compilation of dependencies. + +# Using Workspaces +## Examples Structure +``` scss +my_project/ +├── Cargo.toml (workspace root) +├── crate1/ +│ ├── Cargo.toml +│ └── src/ +├── crate2/ +│ ├── Cargo.toml +│ └── src/ +└── target/ +``` + +## Building and Testing +- Build entire workspace: `cargo build`. +- Test specific crate: `cargo test -p crate1`. + +# Installing Binaries with Cargo +## Installing Binary Crates +- Use `cargo install`: +``` sh +cargo install ripgrep +``` +- Binaries stored in `~/.cargo/bin` (add to `$PATH`). + +- Run the tool: +``` sh +rg --help +``` + +# Extending Cargo with Custom Commands +## Custom Commands +- Name binaries as `cargo-`. +- Accessible via `cargo `. + +## Example: +- A binary named `cargo-fancy`: +``` sh +cargo fancy +``` +Benefits: +- Extend Cargo without modifying it. +- Automatically integrates into `cargo --list`. + +# Summary +- Custom builds: Optimize dev and release profiles. +- Publishing: Share crates via crates.io with clear documentation. +- Workspaces: Manage multi-crate projects with shared dependencies. +- Binaries: Install and use tools with cargo install. +- Extensions: Create custom Cargo commands for specialized workflows. From c49e3df0f022505ddba4a54da7135072f884e050 Mon Sep 17 00:00:00 2001 From: Jackson Hoffart Date: Mon, 25 Nov 2024 11:04:41 +0100 Subject: [PATCH 3/6] update chapter 14 --- slides/14-more_about_cargo_and_cratesio.qmd | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/slides/14-more_about_cargo_and_cratesio.qmd b/slides/14-more_about_cargo_and_cratesio.qmd index 864afe7..37cfc07 100644 --- a/slides/14-more_about_cargo_and_cratesio.qmd +++ b/slides/14-more_about_cargo_and_cratesio.qmd @@ -6,7 +6,7 @@ title: "14. More about Cargo and Crates.io" # Learning Objectives - Learn more about Cargo's advanced features: - Customizing builds with release profiles. - - Publishing libraries to crates.io. + - Publishing libraries to [crates.io](https://crates.io/). - Managing multi-crate projects with workspaces. - Installing binaries using Cargo. - Extending Cargo with custom commands. @@ -26,7 +26,7 @@ opt-level = 0 [profile.release] opt-level = 3 ``` -- opt-level: Optimization levels (0-3). +- `opt-level`: Optimization levels (0-3). - Development: Minimize build time. - Production: Maximize runtime performance. @@ -132,8 +132,8 @@ Benefits: - Automatically integrates into `cargo --list`. # Summary -- Custom builds: Optimize dev and release profiles. -- Publishing: Share crates via crates.io with clear documentation. -- Workspaces: Manage multi-crate projects with shared dependencies. -- Binaries: Install and use tools with cargo install. -- Extensions: Create custom Cargo commands for specialized workflows. +- Optimize builds using dev and release profiles. +- Publish crates to crates.io (with clear documentation!). +- Manage multi-crate projects with shared dependencies. +- Install and use binaries with cargo install. +- Create custom Cargo commands for specialized workflows. From a32bc669679ddc0d4b0ab69d366c4542cddcee9a Mon Sep 17 00:00:00 2001 From: Jackson Hoffart Date: Mon, 25 Nov 2024 18:15:21 +0100 Subject: [PATCH 4/6] updates to ch. 7 --- ...jects_with_packages_crates_and_modules.qmd | 43 +++++++++++-------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/slides/07-managing_growing_projects_with_packages_crates_and_modules.qmd b/slides/07-managing_growing_projects_with_packages_crates_and_modules.qmd index 2e2c726..f6e4ff7 100644 --- a/slides/07-managing_growing_projects_with_packages_crates_and_modules.qmd +++ b/slides/07-managing_growing_projects_with_packages_crates_and_modules.qmd @@ -5,11 +5,9 @@ title: "7. Managing Growing Projects with Packages, Crates, and Modules" # Learning objectives -By the end of this session, you should be able to: - ::: nonincremental -- Understand and use Rust's module system (`mod`, `pub`, `use`). - Differentiate between packages, crates, and modules. +- Understand and use Rust's module system (`mod`, `pub`, `use`). - Implement Cargo workspaces for multi-crate projects. - Apply best practices for managing and organizing Rust projects. ::: @@ -22,10 +20,10 @@ Encourage questions about any points that feel unclear. ## Key Concepts -- **Package**: A bundle of one or more crates, defined by a `Cargo.toml` file. -- **Crate**: A compilation unit in Rust (binary or library). +- **Package**: A Cargo feature that lets you build, test and share crates. Defined by a `Cargo.toml` file. +- **Crate**: A tree of modules that produces a library or executable. Rust's compilation unit. - **Module**: A way to organize code and control scope and visibility. -- **Workspace**: A collection of interrelated packages managed together. +- **Paths**: A way of naming an item, such as a struct, function, or module. # Creating and Using Packages @@ -39,19 +37,13 @@ $ cd my_project - Creates a new package with a `Cargo.toml` and a default binary crate. - Binary crate root: `src/main.rs`. - To create a library crate, add a `src/lib.rs`. - -## Example `Cargo.toml` -``` toml -[package] -name = "my_project" -version = "0.1.0" -edition = "2021" - -[dependencies] -rand = "0.8.5" -``` +- An executable crate must have a `main` function as an entry point. +- A library crate can be used by other crates, and does not need a `main` entry point. # Working with Modules +## Backyard example +- Check out the backyard example! + ## Accessing Module Items ``` rust crate::front_of_house::hosting::add_to_waitlist(); @@ -65,15 +57,28 @@ front_of_house::hosting::add_to_waitlist(); ## Controlling Visibility ``` rust -pub mod front_of_house { +mod front_of_house { pub mod hosting { pub fn add_to_waitlist() {} } } + +pub fn eat_at_restaurant() { + // Absolute path + crate::front_of_house::hosting::add_to_waitlist(); + + // Relative path + front_of_house::hosting::add_to_waitlist(); +} ``` - By default, items are private - Use `pub` to make modules, functions, and fields accessible +## No private code in R +- In R, everything is public + - Even un-exported functions can be accessed with `:::`. +- In Rust, private items are not accessible outside their module. + # Using `use` for Convenience ## Simplify Paths ``` rust @@ -81,7 +86,7 @@ use crate::front_of_house::hosting; hosting::add_to_waitlist(); ``` -- Use use to shorten paths. +- Use `use` to shorten paths. - Works within the scope it's defined. ## Re-exporting with `pub use` From deada3be183b4fc07623cfb2aaedaecc323d4e5d Mon Sep 17 00:00:00 2001 From: Jackson Hoffart Date: Mon, 25 Nov 2024 20:50:13 +0100 Subject: [PATCH 5/6] style ch. 14 --- slides/14-more_about_cargo_and_cratesio.qmd | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/slides/14-more_about_cargo_and_cratesio.qmd b/slides/14-more_about_cargo_and_cratesio.qmd index 37cfc07..03d3b83 100644 --- a/slides/14-more_about_cargo_and_cratesio.qmd +++ b/slides/14-more_about_cargo_and_cratesio.qmd @@ -4,12 +4,15 @@ title: "14. More about Cargo and Crates.io" --- # Learning Objectives + +::: nonincremental - Learn more about Cargo's advanced features: - Customizing builds with release profiles. - Publishing libraries to [crates.io](https://crates.io/). - Managing multi-crate projects with workspaces. - Installing binaries using Cargo. - Extending Cargo with custom commands. +::: # Customizing Builds with Release Profiles @@ -27,8 +30,8 @@ opt-level = 0 opt-level = 3 ``` - `opt-level`: Optimization levels (0-3). - - Development: Minimize build time. - - Production: Maximize runtime performance. + - *Development*: Minimize build time. + - *Production*: Maximize runtime performance. # Publishing a Crate to Crates.io ## Steps to Publish @@ -44,7 +47,7 @@ license = "MIT OR Apache-2.0" 4. Run Publish: `cargo publish`. ## Important Notes -- Published versions are permanent. +- Published versions are *permanent*. - You can "yank" a version to prevent new dependencies but retain existing ones. # Writing Documentation for Crates From 213b7ded62e2ac443996a4999946c6412d5d1d68 Mon Sep 17 00:00:00 2001 From: Jackson Hoffart Date: Tue, 26 Nov 2024 09:26:28 +0100 Subject: [PATCH 6/6] add details to ch 7 --- ...ging_growing_projects_with_packages_crates_and_modules.qmd | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/slides/07-managing_growing_projects_with_packages_crates_and_modules.qmd b/slides/07-managing_growing_projects_with_packages_crates_and_modules.qmd index f6e4ff7..0ea69a7 100644 --- a/slides/07-managing_growing_projects_with_packages_crates_and_modules.qmd +++ b/slides/07-managing_growing_projects_with_packages_crates_and_modules.qmd @@ -22,6 +22,8 @@ Encourage questions about any points that feel unclear. - **Package**: A Cargo feature that lets you build, test and share crates. Defined by a `Cargo.toml` file. - **Crate**: A tree of modules that produces a library or executable. Rust's compilation unit. + - **Binary crate**: An executable with a `main` function as an entry point. + - **Library crate**: A crate that can be used by other crates. - **Module**: A way to organize code and control scope and visibility. - **Paths**: A way of naming an item, such as a struct, function, or module. @@ -41,7 +43,7 @@ $ cd my_project - A library crate can be used by other crates, and does not need a `main` entry point. # Working with Modules -## Backyard example +## Control Scope and Privacy with Modules - Check out the backyard example! ## Accessing Module Items