From c6299ee523773c12def7aefbe36ca4b51467db6f Mon Sep 17 00:00:00 2001 From: darkicewolf50 Date: Tue, 14 Jan 2025 21:53:50 -0700 Subject: [PATCH] finished ch7.2 and started ch7.3 --- .obsidian/workspace.json | 8 ++--- Crates.md | 2 ++ Modules and Use.md | 6 ++++ Paths.md | 66 ++++++++++++++++++++++++++++++++++++++++ Project Organization.md | 4 ++- 5 files changed, 81 insertions(+), 5 deletions(-) create mode 100644 Paths.md diff --git a/.obsidian/workspace.json b/.obsidian/workspace.json index 602188a..617d4ce 100644 --- a/.obsidian/workspace.json +++ b/.obsidian/workspace.json @@ -41,13 +41,12 @@ "state": { "type": "markdown", "state": { - "file": "Modules and Use.md", + "file": "Project Organization.md", "mode": "source", - "backlinks": false, "source": false }, "icon": "lucide-file", - "title": "Modules and Use" + "title": "Project Organization" } }, { @@ -209,9 +208,11 @@ }, "active": "773e0725828dabb7", "lastOpenFiles": [ + "Paths.md", "Project Organization.md", "Modules and Use.md", "Crates.md", + "Untitled.canvas", "Packages.md", "Enums.md", "Primitives.md", @@ -223,7 +224,6 @@ "ownership.md", "Variables.md", "README.md", - "Untitled.canvas", "Constants.md", "Structures.md" ] diff --git a/Crates.md b/Crates.md index a297b4b..79c972e 100644 --- a/Crates.md +++ b/Crates.md @@ -20,6 +20,8 @@ instead it defines functionality that is intended to be shared with multiple pro most of the time when the term "crate" is said it means a library crate and crate is used interchangeably with the term library with other languages +these can be created by ``cargo new crate_name --lib`` + ## Root Crate this is the source file that the compiler starts from and makes up the root module of your crate diff --git a/Modules and Use.md b/Modules and Use.md index 71a367f..239f744 100644 --- a/Modules and Use.md +++ b/Modules and Use.md @@ -70,3 +70,9 @@ pub struct Asparagus {} ``` ## Grouping Related Code in Modules +used to group code together and make easier to reuse +modules allow for the control of privacy, implementations needs to be declared as public otherwise it will be private by default not available to other modules if private + +public modules and implementations can allow for different code to depend on it + +this should be used to organize code like a file directory \ No newline at end of file diff --git a/Paths.md b/Paths.md new file mode 100644 index 0000000..31a57b3 --- /dev/null +++ b/Paths.md @@ -0,0 +1,66 @@ +# Paths + +## Paths for Referring to an Item in the Module Tree +to show the rust compiler where to find an item in a module tree we use a path similar to navigating a filesystem, where the function is located + +A path can be two forms: +- *Absolute path* - the full path starting from a crate root to the code of an external crate, the absolute path begins with the crate name and for code form the current crate it starts with the literal *crate* +- *Relative path* - starts from the current module and uses ``self``, ``super``, or an identifier in the current module +Both types of paths are followed by one or more identifiers separated by ``::`` + +module tree for example +``` +crate + └── front_of_house + ├── hosting + │ ├── add_to_waitlist + │ └── seat_at_table + └── serving + ├── take_order + ├── serve_order + └── take_payment +``` + +```rust + // Absolute path + crate::front_of_house::hosting::add_to_waitlist(); + + // Relative path + front_of_house::hosting::add_to_waitlist(); +``` + +these are both calls to different parts of a different module from the parent crate named ``crate`` +this is equivalent to ``/front_of_house/hosting/add_to_waitlist`` in another language where the first ``/`` is the crate root or the ``./`` + +choose the pathing based off your requirements/future organization of code +preference is to specify absolute paths because more likely to move code definitions and item calls independently of each other + +rust will be able to tell the difference between a private function and a wrong path error + +any function, method, struct, enum, module and constants are private by default + +child modules can use parent modules but parent modules cannot use child modules + +child modules wrap their implementation to those above but not to itself or below + +you use pub keyword to expose to the parent module +this is done so that you know what breaks your code + +this is valid and allows for the outermost crate to access the function add_to_watlist through the root defined front_of_house module +```rust +mod front_of_house { + pub mod hosting { + pub fn add_to_waitlist() {} + } +} +``` + +it is called by ``crate::front_of_house::hosting::add_to_waitlist();`` +from the sister module/function +if it was up another level then front_of_house would need a pub + +can be called by the relative path ``front_of_house::hosting::add_to_waitlist();`` + +the public API that is determined by the developer is the contract with the users through other crates. +There are many considerations to your public api to make it easier for people to depend on your crate +These details and considerations are more concretely outlined in the [The Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) diff --git a/Project Organization.md b/Project Organization.md index bbea3d0..7ccceb4 100644 --- a/Project Organization.md +++ b/Project Organization.md @@ -15,4 +15,6 @@ These features are known collectively as the ``module system`` they include - [**Packages**](Packages.md): A feature of Cargo that allows you to build, test and share crates - [**Crates**](Crates.md): A tree of modules that produces a library or an executable - [**Modules** and **use**](Modules%20and%20Use.md): lets you control the organization, scope and privacy of paths -- **Paths**: A way of naming an item, such as a struct, function or module +- [**Paths**](Paths.md): A way of naming an item, such as a struct, function or module + +## Best Practices for Packages with a Binary and a Library