From 3bac2f0c8feddbd772a8ae57e2bc8ec95882985c Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Mon, 19 Feb 2018 14:09:53 -0500 Subject: [PATCH] According to our conventions, this should be a separate file --- second-edition/src/SUMMARY.md | 1 + second-edition/src/ch01-02-hello-world.md | 266 ---------------------- second-edition/src/ch01-03-hello-cargo.md | 265 +++++++++++++++++++++ 3 files changed, 266 insertions(+), 266 deletions(-) create mode 100644 second-edition/src/ch01-03-hello-cargo.md diff --git a/second-edition/src/SUMMARY.md b/second-edition/src/SUMMARY.md index e34531d09..6cf7a8908 100644 --- a/second-edition/src/SUMMARY.md +++ b/second-edition/src/SUMMARY.md @@ -7,6 +7,7 @@ - [Getting Started](ch01-00-getting-started.md) - [Installation](ch01-01-installation.md) - [Hello, World!](ch01-02-hello-world.md) + - [Hello, Cargo!](ch01-03-hello-cargo.md) - [Guessing Game Tutorial](ch02-00-guessing-game-tutorial.md) diff --git a/second-edition/src/ch01-02-hello-world.md b/second-edition/src/ch01-02-hello-world.md index fefe3e241..279a6a3ae 100644 --- a/second-edition/src/ch01-02-hello-world.md +++ b/second-edition/src/ch01-02-hello-world.md @@ -216,269 +216,3 @@ Just compiling with `rustc` is fine for simple programs, but as your project grows, you’ll want to be able to manage all of the options and make it easy to share your code. Next, we’ll introduce you to a tool called Cargo, which will help you write real-world Rust programs. - -## Hello, Cargo! - -Cargo is Rust’s build system and package manager. Most Rustaceans will use this -tool to manage their Rust projects because Cargo takes care of a lot of tasks -for you, such as building your code, downloading the libraries your code -depends on, and building those libraries. (We call libraries your code needs -*dependencies*.) - -The simplest Rust programs, like the one we’ve written so far, don’t have any -dependencies, so if we had built the Hello World project with Cargo, it would -only be using the part of Cargo that takes care of building your code. As you -write more complex Rust programs, you’ll want to add dependencies, and if you -start the project off using Cargo, that will be a lot easier to do. - -As the vast majority of Rust projects use Cargo, the rest of this book will -assume that you're using Cargo too. Cargo comes installed with Rust itself, if -you used the official installers as covered in the “Installation” section. If -you installed Rust through some other means, you can check if you have Cargo -installed by entering the following into your terminal: - -```text -$ cargo --version -``` - -If you see a version number, great! If you see an error like `command not -found`, then you should look at the documentation for your method of -installation to determine how to install Cargo separately. - -### Creating a Project with Cargo - -Let’s create a new project using Cargo and look at how it differs from our -original Hello World project. Navigate back to your *projects* directory (or -wherever you decided to put your code) and then on any operating system run: - -```text -$ cargo new hello_cargo --bin -$ cd hello_cargo -``` - - - - -This creates a new binary executable called `hello_cargo`. The `--bin` argument -to passed to `cargo new` makes an executable application (often just called a -*binary*), as opposed to a library. We’ve given `hello_cargo` as the name for -our project, and Cargo creates its files in a directory of the same name. - -Go into the *hello_cargo* directory and list the files, and you should see that -Cargo has generated two files and one directory for us: a *Cargo.toml* and a -*src* directory with a *main.rs* file inside. It has also initialized a new git -repository, along with a *.gitignore* file. - -> Note: Git is a common version control system. You can change `cargo new` to -> use a different version control system, or no version control system, by -> using the `--vcs` flag. Run `cargo new --help` to see the available options. - -Open up *Cargo.toml* in your text editor of choice. It should look similar to -the code in Listing 1-2: - -Filename: Cargo.toml - -```toml -[package] -name = "hello_cargo" -version = "0.1.0" -authors = ["Your Name "] - -[dependencies] -``` - -Listing 1-2: Contents of *Cargo.toml* generated by `cargo -new` - -This file is in the [*TOML*][toml] (Tom’s Obvious, Minimal -Language) format, which is what Cargo uses as its configuration format. - -[toml]: https://github.com/toml-lang/toml - -The first line, `[package]`, is a section heading that indicates that the -following statements are configuring a package. As we add more information to -this file, we’ll add other sections. - -The next three lines set the configuration information Cargo needs in order to -know that it should compile your program: the name, the version, and who wrote -it. Cargo gets your name and email information from your environment, so if -that's not correct, go ahead and fix that and save the file. - -The last line, `[dependencies]`, is the start of a section for you to list any -of your project's dependencies. In Rust, packages of code are referred to as -*crates*. We won’t need any other crates for this project, but we will in the -first project in Chapter 2, so we'll use this dependencies section then. - -Now open up *src/main.rs* and take a look: - -Filename: src/main.rs - -```rust -fn main() { - println!("Hello, world!"); -} -``` - -Cargo has generated a “Hello World!” for you, just like the one we wrote in -Listing 1-1! So far, the differences between our previous project and the -project generated by Cargo are that with Cargo our code goes in the *src* -directory, and we have a *Cargo.toml* configuration file in the top directory. - -Cargo expects your source files to live inside the *src* directory so that the -top-level project directory is just for READMEs, license information, -configuration files, and anything else not related to your code. In this way, -using Cargo helps you keep your projects nice and tidy. There’s a place for -everything, and everything is in its place. - -If you started a project that doesn’t use Cargo, as we did with our project in -the *hello_world* directory, you can convert it to a project that does use -Cargo by moving the project code into the *src* directory and creating an -appropriate *Cargo.toml*. - -### Building and Running a Cargo Project - -Now let’s look at what’s different about building and running your Hello World -program through Cargo! From your project directory, build your project by -entering the following commands: - -```text -$ cargo build - Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo) - Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs -``` - -This creates an executable file in *target/debug/hello_cargo* (or -*target\\debug\\hello_cargo.exe* on Windows), which you can run with this -command: - -```text -$ ./target/debug/hello_cargo # or .\target\debug\hello_cargo.exe on Windows -Hello, world! -``` - -Bam! If all goes well, `Hello, world!` should print to the terminal once more. -Running `cargo build` for the first time also causes Cargo to create a new file -at the top level called *Cargo.lock*, which is used to keep track of the exact -versions of dependencies in your project. This project doesn’t have -dependencies, so the file is a bit sparse. You won’t ever need to touch this -file yourself; Cargo will manage its contents for you. - -We just built a project with `cargo build` and ran it with -`./target/debug/hello_cargo`, but we can also use `cargo run` to compile and -then run all in one go: - -```text -$ cargo run - Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs - Running `target/debug/hello_cargo` -Hello, world! -``` - -Notice that this time, we didn’t see the output telling us that Cargo was -compiling `hello_cargo`. Cargo figured out that the files haven’t changed, so -it just ran the binary. If you had modified your source code, Cargo would have -rebuilt the project before running it, and you would have seen output like this: - -```text -$ cargo run - Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo) - Finished dev [unoptimized + debuginfo] target(s) in 0.33 secs - Running `target/debug/hello_cargo` -Hello, world! -``` - -Finally, there’s `cargo check`. This command will quickly check your code to -make sure that it compiles, but not bother producing an executable: - -```text -$ cargo check - Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo) - Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs -``` - -Why would you not want an executable? `cargo check` is often much faster than -`cargo build`, because it skips the entire step of producing the executable. If -your’re checking your work throughout the process of writing the code, using -`cargo check` will speed things up! As such, many Rustaceans run `cargo check` -periodically as they write their program to make sure that it compiles, and -then run `cargo build` once they’re ready to give it a spin themselves. - -So to recap, using Cargo: - -- We can build a project using `cargo build` or `cargo check` -- We can build and run the project in one step with `cargo run` -- Instead of the result of the build being put in the same directory as our - code, Cargo will put it in the *target/debug* directory. - -A final advantage of using Cargo is that the commands are the same no matter -what operating system you’re on, so at this point we will no longer be -providing specific instructions for Linux and Mac versus Windows. - -### Building for Release - -When your project is finally ready for release, you can use `cargo build ---release` to compile your project with optimizations. This will create an -executable in *target/release* instead of *target/debug*. These optimizations -make your Rust code run faster, but turning them on makes your program take -longer to compile. This is why there are two different profiles: one for -development when you want to be able to rebuild quickly and often, and one for -building the final program you’ll give to a user that won’t be rebuilt -repeatedly and that will run as fast as possible. If you’re benchmarking the -running time of your code, be sure to run `cargo build --release` and benchmark -with the executable in *target/release*. - -### Cargo as Convention - -With simple projects, Cargo doesn’t provide a whole lot of value over just -using `rustc`, but it will prove its worth as you continue. With complex -projects composed of multiple crates, it’s much easier to let Cargo coordinate -the build. - -Even though the `hello_cargo` project is simple, it now uses much of the real -tooling you’ll use for the rest of your Rust career. In fact, to work on any -existing projects you can use the following commands to check out the code -using Git, change into the project directory, and build: - -```text -$ git clone someurl.com/someproject -$ cd someproject -$ cargo build -``` - -If you want to look at Cargo in more detail, check out [its documentation]. - -[its documentation]: https://doc.rust-lang.org/cargo/ - - - - -## Summary - -You’re already off to a great start on your Rust journey! In this chapter, -you’ve: - -* Installed the latest stable version of Rust -* Written a “Hello, world!” program using both `rustc` directly and using - the conventions of `cargo` - -This is a great time to build a more substantial program, to get used to -reading and writing Rust code. In the next chapter, we’ll build a guessing game -program. If you’d rather start by learning about how common programming -concepts work in Rust, see Chapter 3. diff --git a/second-edition/src/ch01-03-hello-cargo.md b/second-edition/src/ch01-03-hello-cargo.md new file mode 100644 index 000000000..6c604eb65 --- /dev/null +++ b/second-edition/src/ch01-03-hello-cargo.md @@ -0,0 +1,265 @@ +## Hello, Cargo! + +Cargo is Rust’s build system and package manager. Most Rustaceans will use this +tool to manage their Rust projects because Cargo takes care of a lot of tasks +for you, such as building your code, downloading the libraries your code +depends on, and building those libraries. (We call libraries your code needs +*dependencies*.) + +The simplest Rust programs, like the one we’ve written so far, don’t have any +dependencies, so if we had built the Hello World project with Cargo, it would +only be using the part of Cargo that takes care of building your code. As you +write more complex Rust programs, you’ll want to add dependencies, and if you +start the project off using Cargo, that will be a lot easier to do. + +As the vast majority of Rust projects use Cargo, the rest of this book will +assume that you're using Cargo too. Cargo comes installed with Rust itself, if +you used the official installers as covered in the “Installation” section. If +you installed Rust through some other means, you can check if you have Cargo +installed by entering the following into your terminal: + +```text +$ cargo --version +``` + +If you see a version number, great! If you see an error like `command not +found`, then you should look at the documentation for your method of +installation to determine how to install Cargo separately. + +### Creating a Project with Cargo + +Let’s create a new project using Cargo and look at how it differs from our +original Hello World project. Navigate back to your *projects* directory (or +wherever you decided to put your code) and then on any operating system run: + +```text +$ cargo new hello_cargo --bin +$ cd hello_cargo +``` + + + + +This creates a new binary executable called `hello_cargo`. The `--bin` argument +to passed to `cargo new` makes an executable application (often just called a +*binary*), as opposed to a library. We’ve given `hello_cargo` as the name for +our project, and Cargo creates its files in a directory of the same name. + +Go into the *hello_cargo* directory and list the files, and you should see that +Cargo has generated two files and one directory for us: a *Cargo.toml* and a +*src* directory with a *main.rs* file inside. It has also initialized a new git +repository, along with a *.gitignore* file. + +> Note: Git is a common version control system. You can change `cargo new` to +> use a different version control system, or no version control system, by +> using the `--vcs` flag. Run `cargo new --help` to see the available options. + +Open up *Cargo.toml* in your text editor of choice. It should look similar to +the code in Listing 1-2: + +Filename: Cargo.toml + +```toml +[package] +name = "hello_cargo" +version = "0.1.0" +authors = ["Your Name "] + +[dependencies] +``` + +Listing 1-2: Contents of *Cargo.toml* generated by `cargo +new` + +This file is in the [*TOML*][toml] (Tom’s Obvious, Minimal +Language) format, which is what Cargo uses as its configuration format. + +[toml]: https://github.com/toml-lang/toml + +The first line, `[package]`, is a section heading that indicates that the +following statements are configuring a package. As we add more information to +this file, we’ll add other sections. + +The next three lines set the configuration information Cargo needs in order to +know that it should compile your program: the name, the version, and who wrote +it. Cargo gets your name and email information from your environment, so if +that's not correct, go ahead and fix that and save the file. + +The last line, `[dependencies]`, is the start of a section for you to list any +of your project's dependencies. In Rust, packages of code are referred to as +*crates*. We won’t need any other crates for this project, but we will in the +first project in Chapter 2, so we'll use this dependencies section then. + +Now open up *src/main.rs* and take a look: + +Filename: src/main.rs + +```rust +fn main() { + println!("Hello, world!"); +} +``` + +Cargo has generated a “Hello World!” for you, just like the one we wrote in +Listing 1-1! So far, the differences between our previous project and the +project generated by Cargo are that with Cargo our code goes in the *src* +directory, and we have a *Cargo.toml* configuration file in the top directory. + +Cargo expects your source files to live inside the *src* directory so that the +top-level project directory is just for READMEs, license information, +configuration files, and anything else not related to your code. In this way, +using Cargo helps you keep your projects nice and tidy. There’s a place for +everything, and everything is in its place. + +If you started a project that doesn’t use Cargo, as we did with our project in +the *hello_world* directory, you can convert it to a project that does use +Cargo by moving the project code into the *src* directory and creating an +appropriate *Cargo.toml*. + +### Building and Running a Cargo Project + +Now let’s look at what’s different about building and running your Hello World +program through Cargo! From your project directory, build your project by +entering the following commands: + +```text +$ cargo build + Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo) + Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs +``` + +This creates an executable file in *target/debug/hello_cargo* (or +*target\\debug\\hello_cargo.exe* on Windows), which you can run with this +command: + +```text +$ ./target/debug/hello_cargo # or .\target\debug\hello_cargo.exe on Windows +Hello, world! +``` + +Bam! If all goes well, `Hello, world!` should print to the terminal once more. +Running `cargo build` for the first time also causes Cargo to create a new file +at the top level called *Cargo.lock*, which is used to keep track of the exact +versions of dependencies in your project. This project doesn’t have +dependencies, so the file is a bit sparse. You won’t ever need to touch this +file yourself; Cargo will manage its contents for you. + +We just built a project with `cargo build` and ran it with +`./target/debug/hello_cargo`, but we can also use `cargo run` to compile and +then run all in one go: + +```text +$ cargo run + Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs + Running `target/debug/hello_cargo` +Hello, world! +``` + +Notice that this time, we didn’t see the output telling us that Cargo was +compiling `hello_cargo`. Cargo figured out that the files haven’t changed, so +it just ran the binary. If you had modified your source code, Cargo would have +rebuilt the project before running it, and you would have seen output like this: + +```text +$ cargo run + Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo) + Finished dev [unoptimized + debuginfo] target(s) in 0.33 secs + Running `target/debug/hello_cargo` +Hello, world! +``` + +Finally, there’s `cargo check`. This command will quickly check your code to +make sure that it compiles, but not bother producing an executable: + +```text +$ cargo check + Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo) + Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs +``` + +Why would you not want an executable? `cargo check` is often much faster than +`cargo build`, because it skips the entire step of producing the executable. If +your’re checking your work throughout the process of writing the code, using +`cargo check` will speed things up! As such, many Rustaceans run `cargo check` +periodically as they write their program to make sure that it compiles, and +then run `cargo build` once they’re ready to give it a spin themselves. + +So to recap, using Cargo: + +- We can build a project using `cargo build` or `cargo check` +- We can build and run the project in one step with `cargo run` +- Instead of the result of the build being put in the same directory as our + code, Cargo will put it in the *target/debug* directory. + +A final advantage of using Cargo is that the commands are the same no matter +what operating system you’re on, so at this point we will no longer be +providing specific instructions for Linux and Mac versus Windows. + +### Building for Release + +When your project is finally ready for release, you can use `cargo build +--release` to compile your project with optimizations. This will create an +executable in *target/release* instead of *target/debug*. These optimizations +make your Rust code run faster, but turning them on makes your program take +longer to compile. This is why there are two different profiles: one for +development when you want to be able to rebuild quickly and often, and one for +building the final program you’ll give to a user that won’t be rebuilt +repeatedly and that will run as fast as possible. If you’re benchmarking the +running time of your code, be sure to run `cargo build --release` and benchmark +with the executable in *target/release*. + +### Cargo as Convention + +With simple projects, Cargo doesn’t provide a whole lot of value over just +using `rustc`, but it will prove its worth as you continue. With complex +projects composed of multiple crates, it’s much easier to let Cargo coordinate +the build. + +Even though the `hello_cargo` project is simple, it now uses much of the real +tooling you’ll use for the rest of your Rust career. In fact, to work on any +existing projects you can use the following commands to check out the code +using Git, change into the project directory, and build: + +```text +$ git clone someurl.com/someproject +$ cd someproject +$ cargo build +``` + +If you want to look at Cargo in more detail, check out [its documentation]. + +[its documentation]: https://doc.rust-lang.org/cargo/ + + + + +## Summary + +You’re already off to a great start on your Rust journey! In this chapter, +you’ve: + +* Installed the latest stable version of Rust +* Written a “Hello, world!” program using both `rustc` directly and using + the conventions of `cargo` + +This is a great time to build a more substantial program, to get used to +reading and writing Rust code. In the next chapter, we’ll build a guessing game +program. If you’d rather start by learning about how common programming +concepts work in Rust, see Chapter 3.