You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/en/docs/_overview.md
+12-4
Original file line number
Diff line number
Diff line change
@@ -5,10 +5,18 @@ aliases:
5
5
- "/docs"
6
6
---
7
7
8
-
This publication has its origins in the posts I authored on Medium at https://medium.com/learning-rust. However, please note that I have ceased updating the Medium posts. All current and future updates, new content, code, and grammar fixes will be exclusively maintained and released here, https://learning-rust.github.io.
> 🧑💻 I am an expat working in Singapore as a Go Backend and DevOps Engineer. Feel free to reach out if you find any mistakes or anything that needs to be changed, including spelling or grammar errors. Alternatively, you can create a pull request, open an issue, or [share your awesome ideas in this gist](https://gist.github.com/dumindu/00a0be2d175ed5ff3bc3c17bbf1ca5b6). Good luck with learning Rust!
This publication has its origins in the posts I authored on Medium at https://medium.com/learning-rust. However, please note that I have ceased updating the Medium posts. All current and future updates, new content, code, and grammar fixes will be exclusively maintained and released here, https://learning-rust.github.io.
Copy file name to clipboardExpand all lines: content/en/docs/a1.why-rust.md
+4-2
Original file line number
Diff line number
Diff line change
@@ -36,9 +36,11 @@ Its design elements came from a wide range of sources.
36
36
and etc.
37
37
38
38
39
-
Rust **doesn't use an automated garbage collection** system\(GC\) by default.
39
+
Rust **doesn't use a built-in runtime** or an automated garbage collection system\(GC\).
40
40
41
-
Rust compiler observes the code **at compile-time** and helps to [**prevent many types of errors**](https://doc.rust-lang.org/error-index.html) that are possible to write in C, C++ like programming languages.
41
+
> 💡However, async Rust requires an async runtime, which is provided by community-maintained crates like [`tokio`](https://github.com/tokio-rs/tokio), [`async-std`](https://github.com/async-rs/async-std), [`soml`](https://github.com/smol-rs/smol) etc. The async runtime will be bundled into the final executable.
42
+
43
+
Rust compiler **observes the code at compile-time** and helps to [prevent many types of errors](https://doc.rust-lang.org/error-index.html) that are possible to write in C, C++ like programming languages.
Copy file name to clipboardExpand all lines: content/en/docs/a2.installation.md
+8-6
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ slug: installation
6
6
## Rustup
7
7
There are many ways to install Rust on your system. For the moment the official way to install Rust is using [Rustup](https://rustup.rs/).
8
8
9
-
[📖](https://rust-lang.github.io/rustup/index.html) Rustup installs The Rust Programming Language from the official release channels, enabling you to easily switch between **stable, beta, and nightly** compilers and keep them updated. It makes **cross-compiling** simpler with binary builds of the standard library for common platforms.
9
+
[📖](https://rust-lang.github.io/rustup/index.html) Rustup installs The Rust Programming Language from the official release channels, enabling you to easily switch between **stable, beta, and nightly** compilers and keep them updated. It also makes cross-compiling simpler with binary builds of the standard library for common platforms.
10
10
11
11
[📖](https://rust-lang.github.io/rustup/installation/index.html) Rustup installs **`rustc`, `cargo`, `rustup`** and other standard tools to Cargo's `bin` directory. On Unix it is located at `$HOME/.cargo/bin` and on Windows at `%USERPROFILE%\.cargo\bin`. This is the same directory that `cargo install` will install Rust programs and Cargo plugins.
12
12
@@ -18,8 +18,9 @@ There are many ways to install Rust on your system. For the moment the official
18
18
> -`cargo-fmt`: Helps to run `rustfmt` on whole Rust projects, including multi-crate workspaces.
19
19
> -`cargo-clippy`: A lint tool that provides extra checks for common mistakes and stylistic choices.
20
20
> -`cargo-miri`:An experimental Rust interpreter, which can be used for checking for undefined-behavior.
21
-
> -`rls`: A language server that provides support for editors and IDEs.
22
21
> -`rustdoc`: A local copy of the Rust documentation.
22
+
> -`rust-analyzer`: A language server that provides support for editors and IDEs.
23
+
> -`rust-gdb`: A debugger that wraps GNU Debugger(GDB).
Download **`rustup-init.exe`** from [www.rustup.rs](https://rustup.rs/) and run.
33
34
34
-
> ⭐ If you are on **Microsoft Windows**, you have to install **[Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)** 2015 or higher, which requires an additional 3–4 GBs.
35
+
> 💡 You may need to install [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) 2015 or higher, which requires an additional 3–4 GBs.
35
36
36
37
## 👨🏫 Before going to the next...
37
38
38
-
- To verify the current Rust version, use the **`rustc --version`** or **`rustc -V`** command.
39
-
- Rust ships releases on **six week cycles**. When a new Rust version released, use the **`rustup update`** command to update the Rust ecosystem.
40
-
- To open the offline Rust documentation, use the **`rustup doc`** command. For more `rustup` commands, check the **`rustup --help`** command.
39
+
- To verify the current Rust version, use the **`rustc --version`** or shorter form`rustc -V` command.
40
+
- Rust follows **six week** release cycles. Use the **`rustup update`** command to update the Rust ecosystem.
41
+
- You can access Rust's offline documentation via the `rustup doc` command.
42
+
- For a full list of `rustup` commands, refer to the `rustup --help` command.
|`cargo init`| Create a new project in an existing directory |
14
+
|`cargo check`| Verify the project compiles without errors |
15
+
|`cargo build`| Build the executable |
16
+
|`cargo run`| Build the executable and run |
19
17
20
-
In addition, there are `cargo` commands to publish the project as a crate/ package to **Rust's official crate registry, [crates.io](https://crates.io/)**.
18
+
> 💡 The `cargo check` command verifies that the project compiles without errors, without producing an executable.
19
+
> Thus, it is often faster than `cargo build`.
21
20
22
-
> 💡 We need to get an API token from [crates.io](https://crates.io/) to publish a crate to it. The API token can be found in the [Account Settings page](https://crates.io/me), after login to that site. We will discuss more about this under [code organization with crates](/docs/crates#c-using-cratesio).
21
+
> 💡 Cargo places executables compiled with `cargo build` or `cargo run` in the `target/debug/` directory.
22
+
> But, while those built with **`cargo build --release`** for release purposes are stored in `target/release/` directory.
23
+
> Release builds use more optimizations and remove some runtime safety checks to increase performance, although this comes at the cost of longer compile time.
23
24
24
-
- Login to [crates.io](https://crates.io/) with the API token: `cargo login`
25
-
- Make the local crate uploadable to [crates.io](https://crates.io/): `cargo package`
26
-
- Upload the crate to [crates.io](https://crates.io/): `cargo publish`
|`cargo add`| Add a dependency crate to the project |
28
+
|`cargo remove`| Remove a dependency crate from the project |
29
+
|`cargo fetch`| Download the dependencies specified in Cargo.lock |
30
+
|`cargo update`| Update project dependencies |
31
+
32
+
33
+
> 💡 A crate is a package that can be shared via [crates.io](https://crates.io), Rust community’s crate registry.
34
+
> `cargo add`, `cargo remove`, `cargo fetch`, and `cargo update` commands manage project dependencies through the crate hosted on crates.io.
35
+
36
+
> 💡 The `cargo add` command includes a specified crate in the `[dependencies]` section of `Cargo.toml`, while `cargo add --dev` adds a crate to the `[dev-dependencies]` section. This indicates that the crate is only used for development purposes like testing and will not be included in the final compiled code.
|`cargo login`| Login to [crates.io](https://crates.io/) with the API token |
49
+
|`cargo package`| Make the local crate uploadable to [crates.io](https://crates.io/)|
50
+
|`cargo publish`| Upload the crate to [crates.io](https://crates.io/)|
51
+
|`cargo install`| Install a Rust binary |
52
+
|`cargo uninstall`| Uninstall a Rust binary |
53
+
54
+
> 💡 You need to get an API token from [crates.io](https://crates.io/) to publish a crate to it. The API token can be found in the [Account Settings page](https://crates.io/me), after login to that site. We will discuss more about this under [code organization with crates](/docs/crates#c-using-cratesio).
29
55
30
56
## Crate
31
57
32
-
A crate is a package, which can be shared via [crates.io](https://crates.io/). A crate can produce an executable or a library. In other words, it can be a **binary** crate or a **library** crate.
58
+
-A crate is a package, which can be shared via Rust community’s crate registry, [crates.io](https://crates.io/).
33
59
34
-
01.`cargo new crate_name --bin` or `cargo new crate_name`: Produces an executable
35
-
02.`cargo new crate_name --lib`: Produces a library
60
+
- A crate can produce an executable or a library. In other words, it can be a **binary** crate or a **library** crate.
61
+
1.`cargo new crate_name --bin` or `cargo new crate_name`: Produces an executable
62
+
2.`cargo new crate_name --lib`: Produces a library
36
63
37
64
The first one generates,
38
65
@@ -54,8 +81,6 @@ and the second one generates,
54
81
-**src** folder is the place to store the source code.
55
82
- Each crate has an implicit crate root/ entry point. **main.rs** is the crate root for a binary crate and **lib.rs** is the crate root for a library crate.
56
83
57
-
> 💡 When we build a binary crate via `cargo build` or `cargo run`, the executable file will be stored in the **target/debug/** folder. But when building it via **`cargo build --release`** for a release it will be stored in the **target/release/** folder. The release builds are applying more optimizations while compiling the code, to make the code run faster. But it takes more compile time.
58
-
59
84
## Project Structure
60
85
61
86
This is how [Cargo documentation describes](https://doc.rust-lang.org/cargo/guide/project-layout.html) about the recommended project layout,
@@ -68,7 +93,10 @@ This is how [Cargo documentation describes](https://doc.rust-lang.org/cargo/guid
68
93
│ ├── main.rs
69
94
│ ├── lib.rs
70
95
│ └── bin
71
-
│ └── another_executable.rs
96
+
│ ├── another_executable.rs
97
+
│ └── multi_file_executable
98
+
│ ├── main.rs
99
+
│ └── some_module.rs
72
100
├── tests
73
101
│ └── some_integration_tests.rs
74
102
├── benches
@@ -80,20 +108,31 @@ This is how [Cargo documentation describes](https://doc.rust-lang.org/cargo/guid
80
108
- The source code goes in the `src` directory.
81
109
- The default executable file is `src/main.rs`.
82
110
- The default library file is `src/lib.rs`.
83
-
- Other executables can be placed in `src/bin/*.rs`.
111
+
- Other executables can be placed in,
112
+
-`src/bin/*.rs`
113
+
-`src/bin/*/main.rs`
84
114
- Integration tests go in the `tests` directory \(unit tests go in each file they're testing\).
85
115
- Benchmarks go in the `benches` directory.
86
116
- Examples go in the `examples` directory.
87
117
88
118
## Rust Editions
89
119
90
-
After the initial release in 2015, according to the feedback got from user communities, the Rust team was focusing to increase the **productivity** of the language and the ecosystem. After 3 years of hard work in 2018, a new Rust edition was released with new features, simplified syntax and better tooling. We call it **Rust 2018** edition.
120
+
The language has seen a series of improvements every three years through new editions since its initial stable release in 2015, including the initial version, **Rust 2015**, followed by **Rust 2018**, and the latest, **Rust 2021**.
121
+
122
+
The `edition` key in the `Cargo.toml` file denotes the edition of the Rust compiler to be used for compiling the crate. Editions are opt-in, meaning existing crates will not see these changes until they explicitly migrate to the new edition. Rust guarantees backward compatibility between editions, allowing crates using older editions of Rust to interoperate seamlessly with those using newer versions.
91
123
92
-
To keep the promise of supporting backward compatibility, the new `edition = "2018"` configuration was added to the `Cargo.toml` file. For new projects, the `cargo new` command adds this configuration by default. So, you don't need to care. But on legacy crates, if you can not see any `edition` configuration, Cargo will consider it as a Rust 2015 edition crate.
124
+
For new projects created by `cargo new`, it will set `edition = "2021"` by default in the `Cargo.toml` file. For example,
125
+
126
+
```toml
127
+
[package]
128
+
name = "api"
129
+
version = "0.1.0"
130
+
edition = "2021"
131
+
```
93
132
94
133
## 👨🏫 Before going to the next...
95
134
96
-
- The **`.cargo/bin` directory of your home directory** is the default location of Rust binaries. Not only the official binaries like `rustup`, `rustc`, `cargo`, `rustfmt`, `rustdoc`, `rls` and also the binaries you can install via `cargo install` command, will be stored in this directory.
135
+
- The `.cargo/bin` directory of your home directory is the default location of Rust binaries. Not only the official binaries like `rustc`, `cargo`, `rustup`, `rustfmt`, `rustdoc`, `rust-analyzer` and also the binaries you can install via `cargo install` command, will be stored in this directory.
97
136
98
137
- Even though the initial convention for naming crates and file names is using the [`snake_case`](https://en.wikipedia.org/wiki/Snake_case), some crate developers are using `kebab-case` on both crates and file names. To make your code more consistent, use the initial convention `snake_case`; especially on file names.
0 commit comments