Rust Getting Started Guide (modules and engineering structures)

Rust Getting started （modules And engineering structure ）

front

• Rust Getting started （rustup, cargo)
• Rust Getting started （crate Package management ）

First article in , We talked about 「Rust Installation 」 and 「 Use cargo Tool to create a new project 」. In this article , We will learn more about Rust Project structure , And learn more about crates、modules and prelude The concept of .

If you haven't Rust Environmental Science ,

To install Rust Or use https://geekcode.cloud platform ,

Make sure you can create rust project ：

$ cargo new hello_rust

Create a new executable Program , So you can run it directly ：

$ cargo run

cargo First compile and then run ：

$ cargo run
“Hello, World!”

OK, Next we will discuss :

• default Rust Project structure
• main.rs file
• Rust Modules（ file ）
• Rust Modules and visibility
• Rust Modules（ Folder ）
• What is? prelude？

default Rust structure

Rust The default basic structure is as follows , The structure of the folder cannot be changed at will ：

hello_rust
  - src
    - main.rs
  - .gitignore
  - Cargo.toml

We can always use cargo check Command to check the folder structure and Cargo.toml file . If something goes wrong （ For example, I will src Change its name to src1 ）,cargo check Will prompt ：

error: failed to parse manifest at `/Users/geekcode/_working/scratch/hello_rust/Cargo.toml`Caused by:
 no targets specified in the manifest
either src/lib.rs, src/main.rs, a [lib] section, or [[bin]] section must be present

There must be one in the example src/main.rs file , Because we created binaryapplication. If we create library（ stay cargo new Add parameters when --lib ）, that cargo Will create... For us src/lib.rs.

Cargo.lock It's generated automatically , Do not modify . Cargo Initialize a by default Git The repository , It also includes a .gitignore.

/target

perform cargo build Automatically create target Folder , And include building artifacts Folder （ Depending on the configuration, it may be debug or release Folder , The default is debug）.

If you need to cross compile to other platforms , Then a level folder will be added to represent the target platform , Then build the configuration （release or debug）.

And finally main.rs file , It is the portal to the application , The contents are as follows .

main.rs file

default main.rs The file is very simple ：

fn main() {
  println!("Hello, world!");
}

main() function , This is the entrance of our application , It only prints “Helo, World!” To standard output .

Please note that println! Medium println Function is a Rust macro （ An advanced Rust grammatical function ）, The details can be ignored for the time being , Now just remember that it is not a regular function .

Next, we will main.rs Write code happily , Let's first get to know modules .

Modules

In order to make the code more concise , Let's add a struct. Later we will remove this code from the main file , Now just put main.rs Change it to :

struct MyStruct {}

fn main() {
 let _ms = MyStruct {};   <-- Note the '_'
}

This demo It's simple , It clearly describes Rust Module definition of .

Be careful _ Prefix variable name ： If unused variables are defined ,Rust There will be a warning . So we use _ Prefix , It can inform the compiler that this is intentional , Prevent the compiler from issuing warnings . But we don't recommend this in daily development .

Next we will refactor the code , Will be a complex struct Move to another file . Code keeps high cohesion and low coupling , We have created a new document my_struct.rs ：

hello_rust
  - src
    - main.rs
    - my_struct.rs

Files must be added to src/ Under the folder , Then the compiler can find . File naming conventions use snake_case.

hold struct Declaration from main.rs Move to my_struct.rs in ：

// Contents of my_struct.rs
struct MyStruct {}

Build the project ：

$ cargo build

because main.rs Deleted struct Statement , So the following error is displayed ：

Compiling hello_rust v0.1.0 (/scratch/hello_rust)
error[E0422]: cannot find struct, variant or union type `MyStruct` in this scope
 → src/main.rs:2:15
  |
2 | let _ms = MyStruct {};
  |^^^^^^^^ not found in this scope
error: aborting due to previous errorFor more information about this error, try `rustc — explain E0422`. error: could not compile `hello_rust`

Rust Tell us it can't be found struct The definition of . We must state clearly modules. If we don't declare ,Rust Will not actively search / compile module.

introduce struct Statement , We need to change main.rs add to module quote , As shown below ：

mod my_struct;
fn main() {
  let _ms = MyStruct {};
}

stay Rust All files and folders in are module. In order to use code in modules , We need to use... First mod grammar import it . Essentially , This is “mod my_struct;” Insert the code in the module at the position of the statement .

Try building again . wait , What is it? ！？ It still doesn't work …… Um. . Let's look at the error message ：

Compiling hello_rust v0.1.0 (/scratch/hello_rust)
error[E0422]: cannot find struct, variant or union type `MyStruct` in this scope
 → src/main.rs:4:15
  |
4 | let _ms = MyStruct {};
  |^^^^^^^^ not found in this scope
  |
help: consider importing this struct
  |
1 |use crate::my_struct::MyStruct;
  |

Although the mistakes are the same , But now there is a useful tip about adding ：

use crate::my_struct::MyStruct;

We will main.rs Change to the following :

mod my_struct;
use crate::my_struct::MyStruct;
fn main() {
  let _ms = MyStruct {};
}

When using mod Statement import module ,Rust Automatically Create a module namespace for it （ To avoid conflict ）, Therefore, we cannot directly access our struct type . The module namespace is automatically taken from the file name （ Because in this case module It's a document ）, therefore **my_struct**::MyStruct; yes use Part of the statement —— It comes from the file name my_struct.rs（ Without file extension ）.

use Statement crate:: Part of it is because all Rust The projects are all crate. Rust Projects can consist of multiple files （modules） form , Files can also be nested in folders （ It's also modules）. Use crate:: Prefix means to access module Root directory of tree .

therefore , Check out our... Again main.rs :

mod my_struct;                  <-- Import the module code, placing
                                    it into the 'my_struct'
                                    namespaceuse 

use crate::my_struct::MyStruct; <-- Map the fully qualified (from
                                    the crate root) struct
                                    declaration to just 'MyStruct'

fn main() {
  let _ms = MyStruct {};        <-- Yay, we found it! .. or did we?
}

Please remember these two points ：

• must Use mod introduce module（ Documents or folders ）.
• use Keyword can easily map a fully qualified type name to a type name .

Modules - visibility

Now let's run the above main.rs New errors will appear ：

Compiling hello_rust v0.1.0 (/scratch/hello_rust)
error[E0603]: struct `MyStruct` is private
 → src/main.rs:2:23
  |
2 | use crate::my_struct::MyStruct;
  |^^^^^^^^ private struct
  |

This tells us , Although we found struct Statement , But the visibility of the module is private , So we can't access it here .

Rust Visibility and Java And other languages are slightly different , There are a few rules to remember ：

• modular Inside All of （ namely /src A file or subfolder in a folder ） You can access Anything else .
• modular external All of Can only Access the public members of the module .

It may seem strange , But it also has some very good functions —— Private functions in the module can be used for unit testing of the module （ Rust Keep unit tests in modules ）. secondly , Each module must declare a public interface , Define which members can be accessed outside the module .

To expose the members of the module , We have to add pub keyword . Let's visit our my_struct.rs File and replace the contents with ：

pub struct MyStruct {}         <-- Add the 'pub' keyword

Now we can successfully build our complex program :)

Be careful ： We can pub In most statements , Include struct、struct Field 、 function 、 Constant etc. .

Modules - Folder

If we want to MyStruct Split into multiple files . Of course , To put the code in a folder .

Rust In the same way （ As modules） Process files and folders , But there is an important difference .

Let's create a name foo/ Folder , our MyStruct yes foo Part of the function . Next, file my_struct.rs Move to /src/foo. namely , The new folder structure should look like ——

- src/
  - main.rs
  -foo/
    - my_struct.rs

Now modify main.rs Include our new module foo Replace my_struct：

mod foo;                   <-- Change the module to match the folder
use crate::foo::MyStruct;  <-- Update the namespace to 'foo'

fn main() {
  let _ms = MyStruct {};
}

We now build （cargo build）, Result error ：

Compiling hello_rust v0.1.0 (/scratch/hello_rust)
error[E0583]:file not found for module `foo`
 → src/main.rs:1:1
  |
1 | mod foo;
  | ^^^^^^^^
  |
  = help:to create the module `foo`, create file “src/foo.rs” or “src/foo/mod.rs”

When referencing folders module when , We use folder names （ Just like for files module equally ）, but Rust You need a folder named mod.rs The file of .

under these circumstances , We can simply put my_struct.rs Rename it to mod.rs.

For completeness, we are foo/ Add a file to the folder , It contains another struct Definition （ The imaginary name is Another）：

// Contents of src/foo/another.rs
pub struct Another {}   <-- We're going to expose this as public
                            from the 'foo' module so that we can
                            use it in main.rs

We import the new module mod.rs file -

// Contents of src/foo/mod.rs
pub mod another;        <-- Add the module import for 'another'
                            Note the use of 'pub' to expose the
                            module 'another' as public from the
                            module 'foo'
pub struct MyStruct {}

Last in main.rs Use our new Another structure

mod foo;
use crate::foo::MyStruct;
use crate::foo::another::Another; <-- Note that 'another' is a
                                      module within 'foo'
fn main() {
  let _ms = MyStruct {};
  let _a = Another {}; <-- Using prefix '_' as before
}

It seems a little wordy , So let's introduce Preludes.

Preludes

modify foo/ Medium mod.rs ：

mod another;              <-- Remove the 'pub' modifier
pub use another::Another; <-- Add a use'ing to map Another directly
                              into 'foo' and make it public
pub struct MyStruct {}

We don't want another Module disclosure . Let's delete pub keyword , And then use use take Another The fully qualified type of maps to foo Namespace （ Because we are foo Module ）.

Last , Modify our main.rs：

mod foo;
use crate::foo::{MyStruct,Another};
fn main() {
  let _ms = MyStruct {};
  let _a = Another {};
}

Please note that , Because we have Another The type name of is mapped to foo Module , We can use use Import multiple names at a time .

This is it. Preludes,Preludes It's a pattern , Can make you open all the types you want .

main.rs :

mod foo;

mod prelude {                            <-- Create module inline
  pub use crate::foo::{MyStruct,Another};<-- Note the 'pub' here!
}

use crate::prelude::*;                    <-- Make the types exposed
                                              in the prelude
                                              available
fn main() {
  let _ms = MyStruct {};
  let _a = Another {};
}

We can also put Preludes Defined as another module （ Use mod)

We can use it like any other module “prelude” modular , For example, in mod.rs In file :

mod another;
pub use another::Another;
use crate::prelude::*;
pub struct MyStruct {}

Although the case It doesn't need to be preludes . But you can find , As long as it's in the preludes As stated in crate、 Standard library type 、 Constants and other modules , You can use it use Statement to quickly access .

Through this module, you can also find ：

• You can use wildcards ::* Import all public names from the module
• have access to crate:: Access the root directory of the module tree （ The main module in this example ）, And you can do this anywhere in the application .

summary

Rust The module system in is definitely one of the more confusing points of the language . But once you know what the module is （ file 、 Folder ） And how to import them （mod）, How to map names to different modules （use）, It began to become simple .

And the most important thing is ,Rust Some file names of have clear meanings （main.rs,lib.rs,mod.rs） Do not modify .

Keep rusty!

---

Join in GeekCode Community Participation defines Cloud Based IDE

---

Click on 【 Read the original 】 visit GeekCode