From 19099f21187c2c67412ffe676c55a6fc0e7709e9 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Mon, 19 Feb 2018 12:37:29 -0500 Subject: [PATCH 01/10] Chapter 1 as received from nostarch With removals of text that's going to the intro --- second-edition/nostarch/chapter01.md | 526 ++++++++++----------------- 1 file changed, 195 insertions(+), 331 deletions(-) diff --git a/second-edition/nostarch/chapter01.md b/second-edition/nostarch/chapter01.md index 07cb24128..c08631104 100644 --- a/second-edition/nostarch/chapter01.md +++ b/second-edition/nostarch/chapter01.md @@ -1,7 +1,11 @@ [TOC] -# Introduction +# Chapter 1: Getting Started + + Welcome to “The Rust Programming Language,” an introductory book about Rust. @@ -12,158 +16,39 @@ Through balancing powerful technical capacity and a great developer experience, Rust gives you the option to control low-level details (such as memory usage) without all the hassle traditionally associated with such control. -## Who Rust is For - -Rust is great for many people for a variety of reasons. Let’s discuss a few of -the most important groups. - -### Teams of Developers - -Rust is proving to be a productive tool for collaborating among large teams of -developers with varying levels of systems programming knowledge. Low-level code -is prone to a variety of subtle bugs, which in most other languages can only be -caught through extensive testing and careful code review by experienced -developers. In Rust, the compiler plays a gatekeeper role by refusing to -compile code with these kinds of bugs--including concurrency bugs. By working -alongside the compiler, the team can spend more time focusing on the logic of -the program rather than chasing down bugs. - -Rust also brings contemporary developer tools to the systems programming world: - -* Cargo, the included dependency manager and build tool, makes adding, - compiling, and managing dependencies painless and consistent across the Rust - ecosystem. -* Rustfmt ensures a consistent coding style across developers. -* The Rust Language Server powers IDE integration for code completion and - inline error messages. - -By using these and other tools in the Rust ecosystem, developers can be -productive while writing systems-level code. - -### Students - -Rust is for students and people who are interested in learning about systems -concepts. Many people have learned about topics like operating systems -development through Rust. The community is happy to answer student questions. -Through efforts such as this book, the Rust teams want to make systems concepts -more accessible to more people, especially those getting started with -programming. - -### Companies - -Rust is used in production by hundreds of companies, large and small, for a -variety of tasks, such as command line tools, web services, DevOps tooling, -embedded devices, audio and video analysis and transcoding, cryptocurrencies, -bioinformatics, search engines, internet of things applications, machine -learning, and even major parts of the Firefox web browser. - -### Open Source Developers - -Rust is for people who want to build the Rust programming language, community, -developer tools, and libraries. We’d love for you to contribute to the Rust -language. - -### People Who Value Speed and Stability - -By speed, we mean both the speed of the programs that Rust lets you create and -the speed at which Rust lets you write them. The Rust compiler’s checks ensure -stability through feature additions and refactoring, as opposed to brittle -legacy code in languages without these checks that developers are afraid to -modify. By striving for zero-cost abstractions, higher level features that -compile to lower level code as fast as code written manually, Rust endeavors to -make safe code be fast code as well. - -This isn’t a complete list of everyone the Rust language hopes to support, but -these are some of the biggest stakeholders. Overall, Rust’s greatest ambition -is to take trade-offs that have been accepted by programmers for decades and -eliminate the dichotomy. Safety *and* productivity. Speed *and* ergonomics. -Give Rust a try, and see if its choices work for you. - -## Who This Book is For - -This book assumes that you’ve written code in some other programming language, -but doesn’t make any assumptions about which one. We’ve tried to make the -material broadly accessible to those from a wide variety of programming -backgrounds. We don’t spend a lot of time talking about what programming *is* -or how to think about it; someone new to programming entirely would be better -served by reading a book specifically providing an introduction to programming. - -## How to Use This Book - -This book generally assumes that you’re reading it front-to-back, that is, -later chapters build on top of concepts in earlier chapters, and earlier -chapters may not dig into details on a topic, revisiting the topic in a later -chapter. - -There are two kinds of chapters in this book: concept chapters, and project -chapters. In concept chapters, you’ll learn about an aspect of Rust. In the -project chapters, we’ll build small programs together, applying what we’ve -learned so far. Chapters 2, 12, and 20 are project chapters; the rest are -concept chapters. - -Additionally, Chapter 2 is a hands-on introduction to Rust as a language. We’ll -cover concepts at a high level, and later chapters will go into them in detail. -If you’re the kind of person who likes to get their hands dirty right away, -Chapter 2 is great for that. If you’re *really* that kind of person, you may -even wish to skip over Chapter 3, which covers features that are very similar -to other programming languages, and go straight to Chapter 4 to learn about -Rust’s ownership system. By contrast, if you’re a particularly meticulous -learner who prefers to learn every detail before moving onto the next, you may -want to skip Chapter 2 and go straight to Chapter 3. - -In the end, there’s no wrong way to read a book: if you want to skip ahead, go -for it! You may have to jump back if you find things confusing. Do whatever -works for you. - -An important part of the process of learning Rust is learning how to read the -error messages that the compiler gives you. As such, we’ll be showing a lot of -code that doesn’t compile, and the error message the compiler will show you in -that situation. As such, if you pick a random example, it may not compile! -Please read the surrounding text to make sure that you didn’t happen to pick -one of the in-progress examples. - -Finally, there are some appendices. These contain useful information about the -language in a more reference-like format. - -## Contributing to the Book - -This book is open source. If you find an error, please don’t hesitate to file -an issue or send a pull request on GitHub at -*https://github.com/rust-lang/book*. Please see CONTRIBUTING.md at -*https://github.com/rust-lang/book/blob/master/CONTRIBUTING.md* for more -details. - ## Installation -The first step to using Rust is to install it. You’ll need an internet -connection to run the commands in this chapter, as we’ll be downloading Rust -from the internet. We’ll actually be installing Rust using `rustup`, a -command-line tool for managing Rust versions and associated tools. +The first step to using Rust is to install it. We'll download Rust through +`rustup`, a command-line tool for managing Rust versions and associated tools. +For this you'll need an internet connection. The following steps will install the latest stable version of the Rust -compiler. The examples and output shown in this book used stable Rust 1.21.0. -Due to Rust’s stability guarantees, which we’ll discuss further in the “How -Rust is Made” section later in this chapter, all of the examples that compile -will continue to compile with newer versions of Rust. The output may differ -slightly as error messages and warnings are often improved. In other words, the -newer, stable version of Rust you will install with these steps should work as -expected with the content of this book. +compiler. The examples and output shown in this book all use stable Rust +1.21.0. Rust’s stability guarantees ensure that all of the examples in the book +that compile will continue to compile with newer versions of Rust. The output +may differ slightly between versions, as error messages and warnings are often +improved. In other words, any newer, stable version of Rust you will install +with these steps should work as expected with the content of this book. + + > #### Command Line Notation > -> We’ll be showing off a number of commands using a terminal, and those lines -> all start with `$`. You don’t need to type in the `$` character; they are -> there to indicate the start of each command. You’ll see many tutorials and -> examples around the web that follow this convention: `$` for commands run as -> a regular user, and `#` for commands you should be running as an -> administrator. Lines that don’t start with `$` are typically showing the -> output of the previous command. Additionally, PowerShell specific examples -> will use `>` rather than `$`. +> In this chapter and throughout the book we’ll be showing some commands used +> in the terminal. Lines that should be entered in a terminal all start with +> `$`. You don’t need to type in the `$` character, it is simply there to +> indicate the start of each command. Many tutorials use this convention: `$` +> for commands run as a regular user, and `#` for commands you should be +> running as an administrator. Lines that don’t start with `$` are typically +> showing the output of the previous command. Additionally, PowerShell specific +> examples will use `>` rather than `$`. + + ### Installing Rustup on Linux or Mac -If you’re on Linux or a Mac, 99% of what you need to do is open a terminal and -type this: +If you’re on Linux or a Mac, you simply need to open a terminal and enter the +following command: ``` $ curl https://sh.rustup.rs -sSf | sh @@ -182,37 +67,38 @@ download, inspect, and run the script however you like. The installation script automatically adds Rust to your system PATH after your next login. If you want to start using Rust right away, run the following -command in your shell: +command in your shell to add Rust to your system PATH manually: + + ``` $ source $HOME/.cargo/env ``` -Alternatively, add the following line to your `~/.bash_profile`: +Alternatively, you can add the following line to your `~/.bash_profile`: ``` $ export PATH="$HOME/.cargo/bin:$PATH" ``` -Finally, you’ll need a linker of some kind. You likely have one installed. If -not, when you compile a Rust program, you’ll get errors that a linker could not -be executed. Check your platform’s documentation for how to install a C -compiler; they usually come with the correct linker as well, given that C needs -one. You may want to install a C compiler regardless of your need for only a -linker; some common Rust packages depend on C code and will need a C compiler -too. +Finally, you’ll need a linker of some kind. It's likely you already have one +installed, but if you try to compile a Rust program and get errors telling you +that a linker could not be executed, you'll need to install one. You can simply +install a C compiler, as that will usually come with the correct linker. Check +your platform’s documentation for how to install a C compiler. Some common Rust +packages depend on C code and will need a C compiler too, so it may be worth +installing one now regardless. ### Installing Rustup on Windows -On Windows, go to https://www.rust-lang.org/en-US/install.html at -*https://www.rust-lang.org/en-US/install.html* and follow the instructions. -You’ll also need the C++ build tools for Visual Studio 2013 or later. The -easiest way to acquire the build tools is by installing Build Tools for Visual -Studio 2017 at *https://www.visualstudio.com/downloads/* which provides only -the Visual C++ build tools. Alternately, you can install at -*https://www.visualstudio.com/downloads/* Visual Studio 2017, Visual Studio -2015, or Visual Studio 2013 and during installation select the desktop -development with C++ workload. +On Windows, go to *https://www.rust-lang.org/en-US/install.html* and follow the +instructions for installing Rust. At some point in the installation you'll +receive a message telling you you’ll also need the C++ build tools for Visual +Studio 2013 or later. The easiest way to acquire the build tools is to install +Build Tools for Visual Studio 2017 at +*https://www.visualstudio.com/downloads/*, found in the Other Tools and +Frameworks section. The rest of this book will use commands that work in both `cmd.exe` and PowerShell. If there are specific differences, we’ll explain which to use. @@ -222,7 +108,7 @@ PowerShell. If there are specific differences, we’ll explain which to use. If you have reasons for preferring not to use `rustup`, please see the Rust installation page at *https://www.rust-lang.org/install.html* for other options. -### Updating +### Updating and Uninstalling Once you have Rust installed via `rustup`, updating to the latest version is easy. From your shell, run the update script: @@ -231,10 +117,8 @@ easy. From your shell, run the update script: $ rustup update ``` -### Uninstalling - -Uninstalling Rust and Rustup is as easy as installing them. From your shell, -run the uninstall script: +To uninstall Rust, from your shell +simply run the uninstall script: ``` $ rustup self uninstall @@ -242,14 +126,14 @@ $ rustup self uninstall ### Troubleshooting -To check that you have Rust installed, you can open up a shell and type this: +To check whether you have Rust installed correctly, open up a shell and enter: ``` $ rustc --version ``` -You should see the version number, commit hash, and commit date in a format -similar to this for the latest stable version at the time you install: +You should see the version number, commit hash, and commit date for the latest +stable version at the time you install in the following format: ``` rustc x.y.z (abcabcabc yyyy-mm-dd) @@ -260,9 +144,9 @@ If you see this, Rust has been installed successfully! Congrats! If you don’t and you’re on Windows, check that Rust is in your `%PATH%` system variable. -If it still isn’t working, there are a number of places where you can get help. -The easiest is the #rust IRC channel on irc.mozilla.org, which you can access -through Mibbit at +If that's all correct and Rust still isn’t working, there are a number of +places you can get help. The easiest is the #rust IRC channel on +irc.mozilla.org, which you can access through Mibbit at *http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust*. Go to that address, and you’ll be chatting with other Rustaceans (a silly nickname we call ourselves) who can help you out. Other great resources include the Users forum @@ -283,8 +167,7 @@ Interface) documentation to find out! Now that you have Rust installed, let’s write your first Rust program. It’s traditional when learning a new language to write a little program to print the -text “Hello, world!” to the screen, and in this section, we’ll follow that -tradition. +text “Hello, world!” to the screen, so we'll do the same here > Note: This book assumes basic familiarity with the command line. Rust itself > makes no specific demands about your editing, tooling, or where your code @@ -297,10 +180,12 @@ tradition. ### Creating a Project Directory First, make a directory to put your Rust code in. Rust doesn’t care where your -code lives, but for this book, we’d suggest making a *projects* directory in -your home directory and keeping all your projects there. Open a terminal and -enter the following commands to make a *projects* directory and a directory -inside that for the “Hello, world!” project: +code lives, but for the exercises and projects in this book, we’d suggest +making a *projects* directory in your home directory and keeping all your +projects there. + +Open a terminal and enter the following commands to make a *projects* directory +and, inside that, a directory for this “Hello, world!” project: Linux and Mac: @@ -331,7 +216,7 @@ Windows PowerShell: ### Writing and Running a Rust Program -Next, make a new source file and call it *main.rs*. Rust files always end with +Next, make a new source file and call it *main.rs*---Rust files always end with the *.rs* extension. If you’re using more than one word in your filename, use an underscore to separate them. For example, you’d use *hello_world.rs* rather than *helloworld.rs*. @@ -349,8 +234,8 @@ fn main() { Listing 1-1: A program that prints “Hello, world!” -Save the file, and go back to your terminal window. On Linux or macOS, enter -the following commands: +Save the file, and go back to your terminal window . On Linux or macOS, enter +the following commands to compile and run the file: ``` $ rustc main.rs @@ -370,6 +255,9 @@ Regardless of your operating system, you should see the string `Hello, world!` print to the terminal. If you did, then congratulations! You’ve officially written a Rust program. That makes you a Rust programmer! Welcome! + + ### Anatomy of a Rust Program Now, let’s go over what just happened in your “Hello, world!” program in @@ -381,14 +269,15 @@ fn main() { } ``` -These lines define a *function* in Rust. The `main` function is special: it’s -the first code that is run for every executable Rust program. The first line -declares a function named `main` that has no parameters and returns nothing. If -there were parameters, their names would go inside the parentheses, `(` and `)`. +These lines define a *function* in Rust. The `main` function is special: it is +always the first code that is run for every executable Rust program. The first +line declares a function named `main` that has no parameters and returns +nothing. If there were parameters, their names would go inside the parentheses, +`(` and `)`. Also note that the function body is wrapped in curly brackets, `{` and `}`. Rust requires these around all function bodies. It’s considered good style to -put the opening curly bracket on the same line as the function declaration, +place the opening curly bracket on the same line as the function declaration, with one space in between. > At the time of writing, an automatic formatter, `rustfmt`, is under @@ -408,46 +297,32 @@ This line does all of the work in this little program: it prints text to the screen. There are a number of details to notice here. The first is that Rust style is to indent with four spaces, not a tab. -The second important part is `println!`. This is calling a Rust *macro*, which -is how metaprogramming is done in Rust. If it were calling a function instead, -it would look like this: `println` (without the `!`). We’ll discuss Rust macros -in more detail in Appendix D, but for now you just need to know that when you -see a `!` that means that you’re calling a macro instead of a normal function. +The second important deatil is the `println!` command. This command is calling +a Rust *macro*. If it were calling a function instead, it would be entered as +`println` (without the `!`). We’ll discuss Rust macros in more detail in +Appendix D, but for now you just need to know that when you see a `!` that +means that you’re calling a macro instead of a normal function. -> ### Why `println!` is a Macro -> -> There are multiple reasons why `println!` is a macro rather than a function, -> and we haven’t really explained Rust yet, so it’s not exactly obvious. Here -> are the reasons: -> -> * The string passed to `println!` can have formatting specifiers in it, -> and those are checked at compile-time. -> * Rust functions can only have a fixed number of arguments, but `println!` -> (and macros generally) can take a variable number. -> * The formatting specifiers can have named arguments, which Rust functions -> cannot. -> * It implicitly takes its arguments by reference even when they’re passed -> by value. -> -> If none of this makes sense, don’t worry about it. We’ll cover these concepts -> in more detail later. + -Next is `"Hello, world!"` which is a *string*. We pass this string as an -argument to `println!`, which prints the string to the screen. Easy enough! +Next comes`"Hello, world!"` which is a *string*. We pass this string as an +argument to `println!` and the total effect is that the string is printed the +string to the screen. Easy enough! -The line ends with a semicolon (`;`). The `;` indicates that this expression is +We end the line with a semicolon `;`, which indicates that this expression is over, and the next one is ready to begin. Most lines of Rust code end with a `;`. ### Compiling and Running Are Separate Steps -In the “Writing and Running a Rust Program” section on page XX, we showed you -how to run a newly created program. We’ll break that process down and examine -each step now. +You've just seen how to run a newly created program, so now let's break that +process down and examine each step now. -Before running a Rust program, you have to compile it. You can use the Rust -compiler by entering the `rustc` command and passing it the name of your source -file, like this: +Before running a Rust program, you have to compile it using the Rust compiler +by entering the `rustc` command and passing it the name of your source file, +like this: ``` $ rustc main.rs @@ -495,30 +370,29 @@ hand, they need to have a Ruby, Python, or JavaScript implementation installed program. Everything is a tradeoff in language design. 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 your project has and -make it easy to share your code with other people and projects. Next, we’ll -introduce you to a tool called Cargo, which will help you write real-world Rust -programs. +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, and Rustaceans use Cargo to -manage their Rust projects because it makes a lot of tasks easier. For example, -Cargo takes care of building your code, downloading the libraries your code -depends on, and building those libraries. We call libraries your code needs -*dependencies*. +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 right now, you’d only be using the part of Cargo that can take -care of building your code. As you write more complex Rust programs, you’ll -want to add dependencies, and if you start off using Cargo, that will be a lot -easier to do. +dependencies, so if we has built your 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, vast majority of Rust projects use Cargo, we will assume that -you’re using it for the rest of the book. 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 typing the following into your terminal: +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: ``` $ cargo --version @@ -531,41 +405,31 @@ 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 -project in `hello_world`. Go back to your projects directory (or wherever you -decided to put your code): - -Linux, Mac, and PowerShell: - -``` -$ cd ~/projects -``` - -CMD for Windows: - -``` -> cd \d "%USERPROFILE%\projects" -``` - -And then on any operating system run: +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: ``` $ cargo new hello_cargo --bin $ cd hello_cargo ``` -We passed the `--bin` argument to `cargo new` because our goal is to make an -executable application, as opposed to a library. Executables are binary -executable files often called just *binaries*. We’ve given `hello_cargo` as the -name for our project, and Cargo creates its files in a directory of the same -name that we can then go into. + -If we list the files in the *hello_cargo* directory, we can 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 in the *hello_cargo* directory for us, along with a *.gitignore* -file. 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. +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 can 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. + +> 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: @@ -583,26 +447,24 @@ authors = ["Your Name "] Listing 1-2: Contents of *Cargo.toml* generated by `cargo new` -This file is in the *TOML* (Tom’s Obvious, Minimal Language) format. TOML is -used as Cargo’s configuration format. +This file is in the *TOML* (Tom’s Obvious, Minimal Language) format, which is +what Cargo uses as its configuration format. 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 three bits of configuration that Cargo needs to -see in order to know that it should compile your program: its name, what -version it is, and who wrote it. Cargo gets your name and email information -from your environment. If it’s not correct, go ahead and fix that and save the -file. +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 it +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 -*crates* (which is what we call packages of Rust code) that your project will -depend on so that Cargo knows to download and compile those too. We won’t need -any other crates for this project, but we will in the guessing game tutorial in -Chapter 2. +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 let’s look at *src/main.rs*: +Now open up *src/main.rs* and take a look: Filename: src/main.rs @@ -613,11 +475,9 @@ fn main() { ``` Cargo has generated a “Hello World!” for you, just like the one we wrote in -Listing 1-1! So that part is the same. The differences between our previous -project and the project generated by Cargo that we’ve seen so far are: - -- Our code goes in the *src* directory -- The top level contains a *Cargo.toml* configuration file +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, @@ -627,13 +487,14 @@ 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 your code into the *src* directory and creating an appropriate -*Cargo.toml*. +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! To do so, enter the following commands: +program through Cargo! From your project directory, build your project by +entering the following commands: ``` $ cargo build @@ -651,16 +512,15 @@ 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*. Cargo uses *Cargo.lock* to keep track of -the exact versions of dependencies used to build 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. +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: +then run all in one go: ``` $ cargo run @@ -672,8 +532,7 @@ 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: +rebuilt the project before running it, and you would have seen output like this: ``` $ cargo run @@ -683,8 +542,8 @@ $ cargo run Hello, world! ``` -Finally, there’s `cargo check`. This will quickly check your code to make sure -that it compiles, but not bother producing an executable: +Finally, there’s `cargo check`. This command will quickly check your code to +make sure that it compiles, but not bother producing an executable: ``` $ cargo check @@ -693,20 +552,21 @@ $ cargo check ``` Why would you not want an executable? `cargo check` is often much faster than -`cargo build`, because Cargo can skip the entire step of producing the -executable. If we’re checking our work throughout the process of writing the -code, this will speed things up! As such, many Rustaceans run `cargo check` 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. +`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 a few more differences we’ve now seen: +So to recap, using Cargo: -- Instead of using `rustc`, build a project using `cargo build` or - `cargo check` (or build and run it in one step with `cargo run`). +- 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. -The other advantage of using Cargo is that the commands are the same no matter +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. @@ -718,24 +578,22 @@ 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 and that -we want to 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*. +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. With Cargo, you can just run `cargo build`, and it should work the -right way. +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, you can get -started with virtually all Rust projects you want to work on with the following -commands to check out the code using Git, change into the project directory, -and build: +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: ``` $ git clone someurl.com/someproject @@ -744,16 +602,26 @@ $ cargo build ``` If you want to look at Cargo in more detail, check out its documentation at -*https://doc.rust-lang.org/cargo/*, which covers all of its features. +*https://doc.rust-lang.org/cargo/*. + + ## How Rust is Made and “Nightly Rust” Before we dive into the language itself, we’d like to finish up the introductory chapter by talking about how Rust is made, and how that affects -you as a Rust developer. We mentioned in the “Installation” section that the -output in this book was generated by stable Rust 1.21.0, but any examples that -compile should continue to compile in any stable version of Rust greater than -that. This section is to explain how we ensure this is true! +you as a Rust developer. We mentioned that the output in this book was +generated by stable Rust 1.21.0, but any examples that compile should continue +to compile in any stable version of Rust greater than that. This section is to +explain how we ensure this is true! ### Stability Without Stagnation @@ -763,14 +631,10 @@ constantly changing, that would be impossible. At the same time, if we can’t experiment with new features, we may not find out important flaws until after their release, when we can no longer change things. -Our solution to this problem is what we call “stability without stagnation” and -is the way we can change and improve Rust while making sure that using Rust -stays nice, stable, and boring. - -Our guiding principle for Rust releases is this: you should never have to fear -upgrading to a new version of stable Rust. Each upgrade should be painless. At -the same time, the upgrade should bring you new features, fewer bugs, and -faster compile times. +Our solution to this problem is what we call “stability without stagnation”, +and our guiding principle is this: you should never have to fear upgrading to a +new version of stable Rust. Each upgrade should be painless, but should also +bring you new features, fewer bugs, and faster compile times. ### Choo, Choo! Release Channels and Riding the Trains @@ -936,12 +800,12 @@ you can write up a proposal, called an RFC. Anyone can write RFCs to improve Rust, and the proposals are reviewed and discussed by the Rust team, which is comprised of many topic subteams. There’s -a full list of the teams on Rust’s -website at *https://www.rust-lang.org/en-US/team.html*, which includes teams for -each area of the project: language design, compiler implementation, -infrastructure, documentation, and more. The appropriate team reads the -proposal and the comments, writes some comments of their own, and eventually, -there’s consensus to accept or reject the feature. +a full list of the teams on Rust’s website at +*https://www.rust-lang.org/en-US/team.html*, which includes teams for each area +of the project: language design, compiler implementation, infrastructure, +documentation, and more. The appropriate team reads the proposal and the +comments, writes some comments of their own, and eventually, there’s consensus +to accept or reject the feature. If the feature is accepted, an issue is opened on the Rust repository, and someone can implement it. The person who implements it very well may not be the From 4fa2deceb06832feccfe18bd17f2c5b55fb26585 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Mon, 19 Feb 2018 12:44:56 -0500 Subject: [PATCH 02/10] Move sections cut from chapter 1 to the introduction --- second-edition/src/SUMMARY.md | 4 +++- .../src/{ch01-00-introduction.md => ch00-00-introduction.md} | 0 second-edition/src/ch01-00-getting-started.md | 3 +++ 3 files changed, 6 insertions(+), 1 deletion(-) rename second-edition/src/{ch01-00-introduction.md => ch00-00-introduction.md} (100%) create mode 100644 second-edition/src/ch01-00-getting-started.md diff --git a/second-edition/src/SUMMARY.md b/second-edition/src/SUMMARY.md index 3e4db6bc7..d82adf106 100644 --- a/second-edition/src/SUMMARY.md +++ b/second-edition/src/SUMMARY.md @@ -1,8 +1,10 @@ # The Rust Programming Language +[Introduction](ch00-00-introduction.md) + ## Getting started -- [Introduction](ch01-00-introduction.md) +- [Getting Started](ch01-00-getting-started.md) - [Installation](ch01-01-installation.md) - [Hello, World!](ch01-02-hello-world.md) - [How Rust is Made and “Nightly Rust”](ch01-03-how-rust-is-made-and-nightly-rust.md) diff --git a/second-edition/src/ch01-00-introduction.md b/second-edition/src/ch00-00-introduction.md similarity index 100% rename from second-edition/src/ch01-00-introduction.md rename to second-edition/src/ch00-00-introduction.md diff --git a/second-edition/src/ch01-00-getting-started.md b/second-edition/src/ch01-00-getting-started.md new file mode 100644 index 000000000..e9dee6f3e --- /dev/null +++ b/second-edition/src/ch01-00-getting-started.md @@ -0,0 +1,3 @@ +# Getting Started + + From 777d13a3932e4ac3173d3e196546ddcc020fda52 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Mon, 19 Feb 2018 13:13:36 -0500 Subject: [PATCH 03/10] Carol's edits in response to nostarch's for chapter 1 --- second-edition/nostarch/chapter01.md | 292 +++--------------- .../src/appendix-07-nightly-rust.md | 204 ++++++++++++ 2 files changed, 254 insertions(+), 242 deletions(-) create mode 100644 second-edition/src/appendix-07-nightly-rust.md diff --git a/second-edition/nostarch/chapter01.md b/second-edition/nostarch/chapter01.md index c08631104..eb54d215b 100644 --- a/second-edition/nostarch/chapter01.md +++ b/second-edition/nostarch/chapter01.md @@ -1,20 +1,18 @@ [TOC] -# Chapter 1: Getting Started +# Getting Started + -Welcome to “The Rust Programming Language,” an introductory book about Rust. +Let's get your Rust journey started! In this chapter, we'll discuss: -Rust is a programming language that helps you write faster, more reliable -software. High-level ergonomics and low-level control are often at odds with -each other in programming language design; Rust stands to challenge that. -Through balancing powerful technical capacity and a great developer experience, -Rust gives you the option to control low-level details (such as memory usage) -without all the hassle traditionally associated with such control. +- Installing Rust on Linux, Mac, or Windows +- Writing a program that prints "Hello, world!" +- Using `cargo`, Rust's package manager and build system ## Installation @@ -47,8 +45,7 @@ with these steps should work as expected with the content of this book. ### Installing Rustup on Linux or Mac -If you’re on Linux or a Mac, you simply need to open a terminal and enter the -following command: +If you’re on Linux or a Mac, open a terminal and enter the following command: ``` $ curl https://sh.rustup.rs -sSf | sh @@ -66,11 +63,15 @@ Of course, if you distrust using `curl URL | sh` to install software, you can download, inspect, and run the script however you like. The installation script automatically adds Rust to your system PATH after your -next login. If you want to start using Rust right away, run the following -command in your shell to add Rust to your system PATH manually: +next login. If you want to start using Rust right away instead of restarting +your terminal, run the following command in your shell to add Rust to your +system PATH manually: + ``` $ source $HOME/.cargo/env @@ -84,7 +85,7 @@ $ export PATH="$HOME/.cargo/bin:$PATH" Finally, you’ll need a linker of some kind. It's likely you already have one installed, but if you try to compile a Rust program and get errors telling you -that a linker could not be executed, you'll need to install one. You can simply +that a linker could not be executed, you'll need to install one. You can install a C compiler, as that will usually come with the correct linker. Check your platform’s documentation for how to install a C compiler. Some common Rust packages depend on C code and will need a C compiler too, so it may be worth @@ -117,8 +118,7 @@ easy. From your shell, run the update script: $ rustup update ``` -To uninstall Rust, from your shell -simply run the uninstall script: +To uninstall Rust and `rustup`, from your shell, run the uninstall script: ``` $ rustup self uninstall @@ -167,7 +167,7 @@ Interface) documentation to find out! Now that you have Rust installed, let’s write your first Rust program. It’s traditional when learning a new language to write a little program to print the -text “Hello, world!” to the screen, so we'll do the same here +text “Hello, world!” to the screen, so we'll do the same here! > Note: This book assumes basic familiarity with the command line. Rust itself > makes no specific demands about your editing, tooling, or where your code @@ -234,7 +234,7 @@ fn main() { Listing 1-1: A program that prints “Hello, world!” -Save the file, and go back to your terminal window . On Linux or macOS, enter +Save the file, and go back to your terminal window. On Linux or macOS, enter the following commands to compile and run the file: ``` @@ -252,11 +252,16 @@ Hello, world! ``` Regardless of your operating system, you should see the string `Hello, world!` -print to the terminal. If you did, then congratulations! You’ve officially +print to the terminal. If you don't see this output, see the "Troubleshooting" +section earlier for ways to get help. + +If you did see `Hello, world!` printed, then congratulations! You’ve officially written a Rust program. That makes you a Rust programmer! Welcome! + ### Anatomy of a Rust Program @@ -297,8 +302,8 @@ This line does all of the work in this little program: it prints text to the screen. There are a number of details to notice here. The first is that Rust style is to indent with four spaces, not a tab. -The second important deatil is the `println!` command. This command is calling -a Rust *macro*. If it were calling a function instead, it would be entered as +The second important deatil is the `println!` call. This code is calling a Rust +*macro*. If it were calling a function instead, it would be entered as `println` (without the `!`). We’ll discuss Rust macros in more detail in Appendix D, but for now you just need to know that when you see a `!` that means that you’re calling a macro instead of a normal function. @@ -306,10 +311,13 @@ means that you’re calling a macro instead of a normal function. + Next comes`"Hello, world!"` which is a *string*. We pass this string as an -argument to `println!` and the total effect is that the string is printed the -string to the screen. Easy enough! +argument to `println!` and the total effect is that the string is printed to +the screen. Easy enough! We end the line with a semicolon `;`, which indicates that this expression is over, and the next one is ready to begin. Most lines of Rust code end with a @@ -318,7 +326,7 @@ over, and the next one is ready to begin. Most lines of Rust code end with a ### Compiling and Running Are Separate Steps You've just seen how to run a newly created program, so now let's break that -process down and examine each step now. +process down and examine each step. Before running a Rust program, you have to compile it using the Rust compiler by entering the `rustc` command and passing it the name of your source file, @@ -383,7 +391,7 @@ 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 has built your Hello World project with Cargo, it would +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. @@ -416,20 +424,28 @@ $ 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 can 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. +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. -> 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. +> 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: @@ -456,7 +472,7 @@ 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 it +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 @@ -560,8 +576,7 @@ 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 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. @@ -613,223 +628,16 @@ readers will want to get stuck in anyway and may skip this and never come back because it's buried at the end of a chapter that's not really related to it. If it's online somewhere separate they can come to it when they're ready. What do you think?--> - -## How Rust is Made and “Nightly Rust” - -Before we dive into the language itself, we’d like to finish up the -introductory chapter by talking about how Rust is made, and how that affects -you as a Rust developer. We mentioned that the output in this book was -generated by stable Rust 1.21.0, but any examples that compile should continue -to compile in any stable version of Rust greater than that. This section is to -explain how we ensure this is true! - -### Stability Without Stagnation - -As a language, Rust cares a *lot* about the stability of your code. We want -Rust to be a rock-solid foundation you can build on, and if things were -constantly changing, that would be impossible. At the same time, if we can’t -experiment with new features, we may not find out important flaws until after -their release, when we can no longer change things. - -Our solution to this problem is what we call “stability without stagnation”, -and our guiding principle is this: you should never have to fear upgrading to a -new version of stable Rust. Each upgrade should be painless, but should also -bring you new features, fewer bugs, and faster compile times. - -### Choo, Choo! Release Channels and Riding the Trains - -Rust development operates on a *train schedule*. That is, all development is -done on the `master` branch of the Rust repository. Releases follow a software -release train model, which has been used by Cisco IOS and other software -projects. There are three *release channels* for Rust: - -* Nightly -* Beta -* Stable - -Most Rust developers primarily use the stable channel, but those who want to -try out experimental new features may use nightly or beta. - -Here’s an example of how the development and release process works: let’s -assume that the Rust team is working on the release of Rust 1.5. That release -happened in December of 2015, but it will provide us with realistic version -numbers. A new feature is added to Rust: a new commit lands on the `master` -branch. Each night, a new nightly version of Rust is produced. Every day is a -release day, and these releases are created by our release infrastructure -automatically. So as time passes, our releases look like this, once a night: - -``` -nightly: * - - * - - * -``` - -Every six weeks, it’s time to prepare a new release! The `beta` branch of the -Rust repository branches off from the `master` branch used by nightly. Now, -there are two releases: - -``` -nightly: * - - * - - * - | -beta: * -``` - -Most Rust users do not use beta releases actively, but test against beta in -their CI system to help Rust discover possible regressions. In the meantime, -there’s still a nightly release every night: - -``` -nightly: * - - * - - * - - * - - * - | -beta: * -``` - -Let’s say a regression is found. Good thing we had some time to test the beta -release before the regression snuck into a stable release! The fix is applied -to `master`, so that nightly is fixed, and then the fix is backported to the -`beta` branch, and a new release of beta is produced: - -``` -nightly: * - - * - - * - - * - - * - - * - | -beta: * - - - - - - - - * -``` - -Six weeks after the first beta was created, it’s time for a stable release! The -`stable` branch is produced from the `beta` branch: - -``` -nightly: * - - * - - * - - * - - * - - * - * - * - | -beta: * - - - - - - - - * - | -stable: * -``` - -Hooray! Rust 1.5 is done! However, we’ve forgotten one thing: because the six -weeks have gone by, we also need a new beta of the *next* version of Rust, 1.6. -So after `stable` branches off of `beta`, the next version of `beta` branches -off of `nightly` again: - -``` -nightly: * - - * - - * - - * - - * - - * - * - * - | | -beta: * - - - - - - - - * * - | -stable: * -``` - -This is called the “train model” because every six weeks, a release “leaves the -station”, but still has to take a journey through the beta channel before it -arrives as a stable release. - -Rust releases every six weeks, like clockwork. If you know the date of one Rust -release, you can know the date of the next one: it’s six weeks later. A nice -aspect of having releases scheduled every six weeks is that the next train is -coming soon. If a feature happens to miss a particular release, there’s no need -to worry: another one is happening in a short time! This helps reduce pressure -to sneak possibly unpolished features in close to the release deadline. - -Thanks to this process, you can always check out the next build of Rust and -verify for yourself that it’s easy to upgrade to: if a beta release doesn’t -work as expected, you can report it to the team and get it fixed before the -next stable release happens! Breakage in a beta release is relatively rare, but -`rustc` is still a piece of software, and bugs do exist. - -### Unstable Features - -There’s one more catch with this release model: unstable features. Rust uses a -technique called “feature flags” to determine what features are enabled in a -given release. If a new feature is under active development, it lands on -`master`, and therefore, in nightly, but behind a *feature flag*. If you, as a -user, wish to try out the work-in-progress feature, you can, but you must be -using a nightly release of Rust and annotate your source code with the -appropriate flag to opt in. - -If you’re using a beta or stable release of Rust, you can’t use any feature -flags. This is the key that allows us to get practical use with new features -before we declare them stable forever. Those who wish to opt into the bleeding -edge can do so, and those who want a rock-solid experience can stick with -stable and know that their code won’t break. Stability without stagnation. - -This book only contains information about stable features, as in-progress -features are still changing, and surely they’ll be different between when this -book was written and when they get enabled in stable builds. You can find -documentation for nightly-only features online. - -### Rustup and the Role of Rust Nightly - -Rustup makes it easy to change between different release channels of Rust, on a -global or per-project basis. By default, you’ll have stable Rust installed. To -install nightly, for example: - -``` -$ rustup install nightly -``` - -You can see all of the *toolchains* (releases of Rust and associated -components) you have installed with `rustup` as well. Here’s an example on one -of your authors’ computers: - -``` -> rustup toolchain list -stable-x86_64-pc-windows-msvc (default) -beta-x86_64-pc-windows-msvc -nightly-x86_64-pc-windows-msvc -``` - -As you can see, the stable toolchain is the default. Most Rust users use stable -most of the time. You might want to use stable most of the time, but use -nightly on a specific project, because you care about a cutting-edge feature. -To do so, you can use `rustup override` in that project’s directory to set the -nightly toolchain as the one `rustup` should use when you’re in that directory: - -``` -$ cd ~/projects/needs-nightly -$ rustup override add nightly -``` - -Now, every time you call `rustc` or `cargo` inside of -*~/projects/needs-nightly*, `rustup` will make sure that you are using nightly -Rust, rather than your default of stable Rust. This comes in handy when you -have a lot of Rust projects! - -### The RFC Process and Teams - -So how do you learn about these new features? Rust’s development model follows -a *Request For Comments (RFC) process*. If you’d like an improvement in Rust, -you can write up a proposal, called an RFC. - -Anyone can write RFCs to improve Rust, and the proposals are reviewed and -discussed by the Rust team, which is comprised of many topic subteams. There’s -a full list of the teams on Rust’s website at -*https://www.rust-lang.org/en-US/team.html*, which includes teams for each area -of the project: language design, compiler implementation, infrastructure, -documentation, and more. The appropriate team reads the proposal and the -comments, writes some comments of their own, and eventually, there’s consensus -to accept or reject the feature. - -If the feature is accepted, an issue is opened on the Rust repository, and -someone can implement it. The person who implements it very well may not be the -person who proposed the feature in the first place! When the implementation is -ready, it lands on the `master` branch behind a feature gate, as we discussed -in the “Unstable Features” section. - -After some time, once Rust developers who use nightly releases have been able -to try out the new feature, team members will discuss the feature, how it’s -worked out on nightly, and decide if it should make it into stable Rust or not. -If the decision is to move forward, the feature gate is removed, and the -feature is now considered stable! It rides the trains into a new stable release -of Rust. + ## Summary You’re already off to a great start on your Rust journey! In this chapter, you’ve: -* Learned what makes Rust unique * Installed the latest stable version of Rust * Written a “Hello, world!” program using both `rustc` directly and using the conventions of `cargo` -* Found out about how Rust is developed 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 diff --git a/second-edition/src/appendix-07-nightly-rust.md b/second-edition/src/appendix-07-nightly-rust.md new file mode 100644 index 000000000..3eaf697af --- /dev/null +++ b/second-edition/src/appendix-07-nightly-rust.md @@ -0,0 +1,204 @@ +# Appendix G - How Rust is Made and “Nightly Rust” + +This appendix is about how Rust is made and how that affects you as a Rust +developer. We mentioned that the output in this book was generated by stable +Rust 1.21.0, but any examples that compile should continue to compile in any +stable version of Rust greater than that. This section is to explain how we +ensure this is true! + +### Stability Without Stagnation + +As a language, Rust cares a *lot* about the stability of your code. We want +Rust to be a rock-solid foundation you can build on, and if things were +constantly changing, that would be impossible. At the same time, if we can’t +experiment with new features, we may not find out important flaws until after +their release, when we can no longer change things. + +Our solution to this problem is what we call “stability without stagnation”, +and our guiding principle is this: you should never have to fear upgrading to a +new version of stable Rust. Each upgrade should be painless, but should also +bring you new features, fewer bugs, and faster compile times. + +### Choo, Choo! Release Channels and Riding the Trains + +Rust development operates on a *train schedule*. That is, all development is +done on the `master` branch of the Rust repository. Releases follow a software +release train model, which has been used by Cisco IOS and other software +projects. There are three *release channels* for Rust: + +* Nightly +* Beta +* Stable + +Most Rust developers primarily use the stable channel, but those who want to +try out experimental new features may use nightly or beta. + +Here’s an example of how the development and release process works: let’s +assume that the Rust team is working on the release of Rust 1.5. That release +happened in December of 2015, but it will provide us with realistic version +numbers. A new feature is added to Rust: a new commit lands on the `master` +branch. Each night, a new nightly version of Rust is produced. Every day is a +release day, and these releases are created by our release infrastructure +automatically. So as time passes, our releases look like this, once a night: + +```text +nightly: * - - * - - * +``` + +Every six weeks, it’s time to prepare a new release! The `beta` branch of the +Rust repository branches off from the `master` branch used by nightly. Now, +there are two releases: + +```text +nightly: * - - * - - * + | +beta: * +``` + +Most Rust users do not use beta releases actively, but test against beta in +their CI system to help Rust discover possible regressions. In the meantime, +there’s still a nightly release every night: + +```text +nightly: * - - * - - * - - * - - * + | +beta: * +``` + +Let’s say a regression is found. Good thing we had some time to test the beta +release before the regression snuck into a stable release! The fix is applied +to `master`, so that nightly is fixed, and then the fix is backported to the +`beta` branch, and a new release of beta is produced: + +```text +nightly: * - - * - - * - - * - - * - - * + | +beta: * - - - - - - - - * +``` + +Six weeks after the first beta was created, it’s time for a stable release! The +`stable` branch is produced from the `beta` branch: + +```text +nightly: * - - * - - * - - * - - * - - * - * - * + | +beta: * - - - - - - - - * + | +stable: * +``` + +Hooray! Rust 1.5 is done! However, we’ve forgotten one thing: because the six +weeks have gone by, we also need a new beta of the *next* version of Rust, 1.6. +So after `stable` branches off of `beta`, the next version of `beta` branches +off of `nightly` again: + +```text +nightly: * - - * - - * - - * - - * - - * - * - * + | | +beta: * - - - - - - - - * * + | +stable: * +``` + +This is called the “train model” because every six weeks, a release “leaves the +station”, but still has to take a journey through the beta channel before it +arrives as a stable release. + +Rust releases every six weeks, like clockwork. If you know the date of one Rust +release, you can know the date of the next one: it’s six weeks later. A nice +aspect of having releases scheduled every six weeks is that the next train is +coming soon. If a feature happens to miss a particular release, there’s no need +to worry: another one is happening in a short time! This helps reduce pressure +to sneak possibly unpolished features in close to the release deadline. + +Thanks to this process, you can always check out the next build of Rust and +verify for yourself that it’s easy to upgrade to: if a beta release doesn’t +work as expected, you can report it to the team and get it fixed before the +next stable release happens! Breakage in a beta release is relatively rare, but +`rustc` is still a piece of software, and bugs do exist. + +### Unstable Features + +There’s one more catch with this release model: unstable features. Rust uses a +technique called “feature flags” to determine what features are enabled in a +given release. If a new feature is under active development, it lands on +`master`, and therefore, in nightly, but behind a *feature flag*. If you, as a +user, wish to try out the work-in-progress feature, you can, but you must be +using a nightly release of Rust and annotate your source code with the +appropriate flag to opt in. + +If you’re using a beta or stable release of Rust, you can’t use any feature +flags. This is the key that allows us to get practical use with new features +before we declare them stable forever. Those who wish to opt into the bleeding +edge can do so, and those who want a rock-solid experience can stick with +stable and know that their code won’t break. Stability without stagnation. + +This book only contains information about stable features, as in-progress +features are still changing, and surely they’ll be different between when this +book was written and when they get enabled in stable builds. You can find +documentation for nightly-only features online. + +### Rustup and the Role of Rust Nightly + +Rustup makes it easy to change between different release channels of Rust, on a +global or per-project basis. By default, you’ll have stable Rust installed. To +install nightly, for example: + +```text +$ rustup install nightly +``` + +You can see all of the *toolchains* (releases of Rust and associated +components) you have installed with `rustup` as well. Here’s an example on one +of your authors’ computers: + +```powershell +> rustup toolchain list +stable-x86_64-pc-windows-msvc (default) +beta-x86_64-pc-windows-msvc +nightly-x86_64-pc-windows-msvc +``` + +As you can see, the stable toolchain is the default. Most Rust users use stable +most of the time. You might want to use stable most of the time, but use +nightly on a specific project, because you care about a cutting-edge feature. +To do so, you can use `rustup override` in that project’s directory to set the +nightly toolchain as the one `rustup` should use when you’re in that directory: + +```text +$ cd ~/projects/needs-nightly +$ rustup override add nightly +``` + +Now, every time you call `rustc` or `cargo` inside of +*~/projects/needs-nightly*, `rustup` will make sure that you are using nightly +Rust, rather than your default of stable Rust. This comes in handy when you +have a lot of Rust projects! + +### The RFC Process and Teams + +So how do you learn about these new features? Rust’s development model follows +a *Request For Comments (RFC) process*. If you’d like an improvement in Rust, +you can write up a proposal, called an RFC. + +Anyone can write RFCs to improve Rust, and the proposals are reviewed and +discussed by the Rust team, which is comprised of many topic subteams. There’s +a full list of the teams [on Rust’s +website](https://www.rust-lang.org/en-US/team.html), which includes teams for +each area of the project: language design, compiler implementation, +infrastructure, documentation, and more. The appropriate team reads the +proposal and the comments, writes some comments of their own, and eventually, +there’s consensus to accept or reject the feature. + +If the feature is accepted, an issue is opened on the Rust repository, and +someone can implement it. The person who implements it very well may not be the +person who proposed the feature in the first place! When the implementation is +ready, it lands on the `master` branch behind a feature gate, as we discussed +in the “Unstable Features” section. + +After some time, once Rust developers who use nightly releases have been able +to try out the new feature, team members will discuss the feature, how it’s +worked out on nightly, and decide if it should make it into stable Rust or not. +If the decision is to move forward, the feature gate is removed, and the +feature is now considered stable! It rides the trains into a new stable release +of Rust. From dc085d5ff9e23f5854e2f6e14f4065cf99eef28a Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Mon, 19 Feb 2018 14:08:48 -0500 Subject: [PATCH 04/10] Propagate changes to src --- second-edition/src/SUMMARY.md | 2 +- second-edition/src/ch01-00-getting-started.md | 9 + second-edition/src/ch01-01-installation.md | 105 ++++--- second-edition/src/ch01-02-hello-world.md | 294 +++++++++--------- ...01-03-how-rust-is-made-and-nightly-rust.md | 226 -------------- 5 files changed, 219 insertions(+), 417 deletions(-) delete mode 100644 second-edition/src/ch01-03-how-rust-is-made-and-nightly-rust.md diff --git a/second-edition/src/SUMMARY.md b/second-edition/src/SUMMARY.md index d82adf106..e34531d09 100644 --- a/second-edition/src/SUMMARY.md +++ b/second-edition/src/SUMMARY.md @@ -7,7 +7,6 @@ - [Getting Started](ch01-00-getting-started.md) - [Installation](ch01-01-installation.md) - [Hello, World!](ch01-02-hello-world.md) - - [How Rust is Made and “Nightly Rust”](ch01-03-how-rust-is-made-and-nightly-rust.md) - [Guessing Game Tutorial](ch02-00-guessing-game-tutorial.md) @@ -131,3 +130,4 @@ - [D - Macros](appendix-04-macros.md) - [E - Translations](appendix-05-translation.md) - [F - Newest Features](appendix-06-newest-features.md) + - [G - How Rust is Made and “Nightly Rust”](appendix-07-nightly-rust.md) diff --git a/second-edition/src/ch01-00-getting-started.md b/second-edition/src/ch01-00-getting-started.md index e9dee6f3e..8c13b60fc 100644 --- a/second-edition/src/ch01-00-getting-started.md +++ b/second-edition/src/ch01-00-getting-started.md @@ -1,3 +1,12 @@ # Getting Started + + +Let's get your Rust journey started! In this chapter, we'll discuss: + +- Installing Rust on Linux, Mac, or Windows +- Writing a program that prints "Hello, world!" +- Using `cargo`, Rust's package manager and build system diff --git a/second-edition/src/ch01-01-installation.md b/second-edition/src/ch01-01-installation.md index 8cf992bc7..299cb29d4 100644 --- a/second-edition/src/ch01-01-installation.md +++ b/second-edition/src/ch01-01-installation.md @@ -1,34 +1,35 @@ ## Installation -The first step to using Rust is to install it. You’ll need an internet -connection to run the commands in this chapter, as we’ll be downloading Rust -from the internet. We’ll actually be installing Rust using `rustup`, a -command-line tool for managing Rust versions and associated tools. +The first step to using Rust is to install it. We'll download Rust through +`rustup`, a command-line tool for managing Rust versions and associated tools. +For this you'll need an internet connection. The following steps will install the latest stable version of the Rust -compiler. The examples and output shown in this book used stable Rust 1.21.0. -Due to Rust’s stability guarantees, which we’ll discuss further in the “How -Rust is Made” section later in this chapter, all of the examples that compile -will continue to compile with newer versions of Rust. The output may differ -slightly as error messages and warnings are often improved. In other words, the -newer, stable version of Rust you will install with these steps should work as -expected with the content of this book. +compiler. The examples and output shown in this book all use stable Rust +1.21.0. Rust’s stability guarantees ensure that all of the examples in the book +that compile will continue to compile with newer versions of Rust. The output +may differ slightly between versions, as error messages and warnings are often +improved. In other words, any newer, stable version of Rust you will install +with these steps should work as expected with the content of this book. + + > #### Command Line Notation > -> We’ll be showing off a number of commands using a terminal, and those lines -> all start with `$`. You don’t need to type in the `$` character; they are -> there to indicate the start of each command. You’ll see many tutorials and -> examples around the web that follow this convention: `$` for commands run as -> a regular user, and `#` for commands you should be running as an -> administrator. Lines that don’t start with `$` are typically showing the -> output of the previous command. Additionally, PowerShell specific examples -> will use `>` rather than `$`. +> In this chapter and throughout the book we’ll be showing some commands used +> in the terminal. Lines that should be entered in a terminal all start with +> `$`. You don’t need to type in the `$` character, it is simply there to +> indicate the start of each command. Many tutorials use this convention: `$` +> for commands run as a regular user, and `#` for commands you should be +> running as an administrator. Lines that don’t start with `$` are typically +> showing the output of the previous command. Additionally, PowerShell specific +> examples will use `>` rather than `$`. + + ### Installing Rustup on Linux or Mac -If you’re on Linux or a Mac, 99% of what you need to do is open a terminal and -type this: +If you’re on Linux or a Mac, open a terminal and enter the following command: ```text $ curl https://sh.rustup.rs -sSf | sh @@ -46,36 +47,42 @@ Of course, if you distrust using `curl URL | sh` to install software, you can download, inspect, and run the script however you like. The installation script automatically adds Rust to your system PATH after your -next login. If you want to start using Rust right away, run the following -command in your shell: +next login. If you want to start using Rust right away instead of restarting +your terminal, run the following command in your shell to add Rust to your +system PATH manually: + + + ```text $ source $HOME/.cargo/env ``` -Alternatively, add the following line to your `~/.bash_profile`: +Alternatively, you can add the following line to your `~/.bash_profile`: ```text $ export PATH="$HOME/.cargo/bin:$PATH" ``` -Finally, you’ll need a linker of some kind. You likely have one installed. If -not, when you compile a Rust program, you’ll get errors that a linker could not -be executed. Check your platform’s documentation for how to install a C -compiler; they usually come with the correct linker as well, given that C needs -one. You may want to install a C compiler regardless of your need for only a -linker; some common Rust packages depend on C code and will need a C compiler -too. +Finally, you’ll need a linker of some kind. It's likely you already have one +installed, but if you try to compile a Rust program and get errors telling you +that a linker could not be executed, you'll need to install one. You can +install a C compiler, as that will usually come with the correct linker. Check +your platform’s documentation for how to install a C compiler. Some common Rust +packages depend on C code and will need a C compiler too, so it may be worth +installing one now regardless. ### Installing Rustup on Windows On Windows, go to [https://www.rust-lang.org/en-US/install.html][install] and -follow the instructions. You’ll also need the C++ build tools for Visual Studio -2013 or later. The easiest way to acquire the build tools is by installing -[Build Tools for Visual Studio 2017][visualstudio] which provides only the -Visual C++ build tools. Alternately, you can [install][visualstudio] Visual -Studio 2017, Visual Studio 2015, or Visual Studio 2013 and during installation -select the desktop development with C++ workload. +follow the instructions for installing Rust. At some point in the installation +you'll receive a message telling you you’ll also need the C++ build tools for +Visual Studio 2013 or later. The easiest way to acquire the build tools is to +install [Build Tools for Visual Studio 2017][visualstudio], found in the Other +Tools and Frameworks section. [install]: https://www.rust-lang.org/en-US/install.html [visualstudio]: https://www.visualstudio.com/downloads/ @@ -88,7 +95,7 @@ PowerShell. If there are specific differences, we’ll explain which to use. If you have reasons for preferring not to use `rustup`, please see [the Rust installation page](https://www.rust-lang.org/install.html) for other options. -### Updating +### Updating and Uninstalling Once you have Rust installed via `rustup`, updating to the latest version is easy. From your shell, run the update script: @@ -97,10 +104,7 @@ easy. From your shell, run the update script: $ rustup update ``` -### Uninstalling - -Uninstalling Rust and Rustup is as easy as installing them. From your shell, -run the uninstall script: +To uninstall Rust and `rustup`, from your shell, run the uninstall script: ```text $ rustup self uninstall @@ -108,14 +112,14 @@ $ rustup self uninstall ### Troubleshooting -To check that you have Rust installed, you can open up a shell and type this: +To check whether you have Rust installed correctly, open up a shell and enter: ```text $ rustc --version ``` -You should see the version number, commit hash, and commit date in a format -similar to this for the latest stable version at the time you install: +You should see the version number, commit hash, and commit date for the latest +stable version at the time you install in the following format: ```text rustc x.y.z (abcabcabc yyyy-mm-dd) @@ -126,11 +130,12 @@ If you see this, Rust has been installed successfully! Congrats! If you don’t and you’re on Windows, check that Rust is in your `%PATH%` system variable. -If it still isn’t working, there are a number of places where you can get help. -The easiest is [the #rust IRC channel on irc.mozilla.org][irc], -which you can access through [Mibbit][mibbit]. Go to that address, and you’ll -be chatting with other Rustaceans (a silly nickname we call ourselves) who can -help you out. Other great resources include [the Users forum][users] and [Stack +If that's all correct and Rust still isn’t working, there are a number of +places you can get help. The easiest is [the #rust IRC channel on +irc.mozilla.org][irc], which you can access through +[Mibbit][mibbit]. Go to that address, and you’ll be chatting with other +Rustaceans (a silly nickname we call ourselves) who can help you out. Other +great resources include [the Users forum][users] and [Stack Overflow][stackoverflow]. [irc]: irc://irc.mozilla.org/#rust diff --git a/second-edition/src/ch01-02-hello-world.md b/second-edition/src/ch01-02-hello-world.md index e124ddf4f..fefe3e241 100644 --- a/second-edition/src/ch01-02-hello-world.md +++ b/second-edition/src/ch01-02-hello-world.md @@ -2,8 +2,7 @@ Now that you have Rust installed, let’s write your first Rust program. It’s traditional when learning a new language to write a little program to print the -text “Hello, world!” to the screen, and in this section, we’ll follow that -tradition. +text “Hello, world!” to the screen, so we'll do the same here! > Note: This book assumes basic familiarity with the command line. Rust itself > makes no specific demands about your editing, tooling, or where your code @@ -16,10 +15,12 @@ tradition. ### Creating a Project Directory First, make a directory to put your Rust code in. Rust doesn’t care where your -code lives, but for this book, we’d suggest making a *projects* directory in -your home directory and keeping all your projects there. Open a terminal and -enter the following commands to make a *projects* directory and a directory -inside that for the “Hello, world!” project: +code lives, but for the exercises and projects in this book, we’d suggest +making a *projects* directory in your home directory and keeping all your +projects there. + +Open a terminal and enter the following commands to make a *projects* directory +and, inside that, a directory for this “Hello, world!” project: Linux and Mac: @@ -50,7 +51,7 @@ Windows PowerShell: ### Writing and Running a Rust Program -Next, make a new source file and call it *main.rs*. Rust files always end with +Next, make a new source file and call it *main.rs*---Rust files always end with the *.rs* extension. If you’re using more than one word in your filename, use an underscore to separate them. For example, you’d use *hello_world.rs* rather than *helloworld.rs*. @@ -69,7 +70,7 @@ fn main() { Listing 1-1: A program that prints “Hello, world!” Save the file, and go back to your terminal window. On Linux or macOS, enter -the following commands: +the following commands to compile and run the file: ```text $ rustc main.rs @@ -86,9 +87,17 @@ Hello, world! ``` Regardless of your operating system, you should see the string `Hello, world!` -print to the terminal. If you did, then congratulations! You’ve officially +print to the terminal. If you don't see this output, see the "Troubleshooting" +section earlier for ways to get help. + +If you did see `Hello, world!` printed, then congratulations! You’ve officially written a Rust program. That makes you a Rust programmer! Welcome! + + + ### Anatomy of a Rust Program Now, let’s go over what just happened in your “Hello, world!” program in @@ -100,14 +109,15 @@ fn main() { } ``` -These lines define a *function* in Rust. The `main` function is special: it’s -the first code that is run for every executable Rust program. The first line -declares a function named `main` that has no parameters and returns nothing. If -there were parameters, their names would go inside the parentheses, `(` and `)`. +These lines define a *function* in Rust. The `main` function is special: it is +always the first code that is run for every executable Rust program. The first +line declares a function named `main` that has no parameters and returns +nothing. If there were parameters, their names would go inside the parentheses, +`(` and `)`. Also note that the function body is wrapped in curly brackets, `{` and `}`. Rust requires these around all function bodies. It’s considered good style to -put the opening curly bracket on the same line as the function declaration, +place the opening curly bracket on the same line as the function declaration, with one space in between. > At the time of writing, an automatic formatter, `rustfmt`, is under @@ -127,45 +137,35 @@ This line does all of the work in this little program: it prints text to the screen. There are a number of details to notice here. The first is that Rust style is to indent with four spaces, not a tab. -The second important part is `println!`. This is calling a Rust *macro*, which -is how metaprogramming is done in Rust. If it were calling a function instead, -it would look like this: `println` (without the `!`). We’ll discuss Rust macros -in more detail in Appendix D, but for now you just need to know that when you -see a `!` that means that you’re calling a macro instead of a normal function. +The second important deatil is the `println!` call. This code is calling a Rust +*macro*. If it were calling a function instead, it would be entered as +`println` (without the `!`). We’ll discuss Rust macros in more detail in +Appendix D, but for now you just need to know that when you see a `!` that +means that you’re calling a macro instead of a normal function. -> ### Why `println!` is a Macro -> -> There are multiple reasons why `println!` is a macro rather than a function, -> and we haven’t really explained Rust yet, so it’s not exactly obvious. Here -> are the reasons: -> -> * The string passed to `println!` can have formatting specifiers in it, -> and those are checked at compile-time. -> * Rust functions can only have a fixed number of arguments, but `println!` -> (and macros generally) can take a variable number. -> * The formatting specifiers can have named arguments, which Rust functions -> cannot. -> * It implicitly takes its arguments by reference even when they’re passed -> by value. -> -> If none of this makes sense, don’t worry about it. We’ll cover these concepts -> in more detail later. + + -Next is `"Hello, world!"` which is a *string*. We pass this string as an -argument to `println!`, which prints the string to the screen. Easy enough! +Next comes`"Hello, world!"` which is a *string*. We pass this string as an +argument to `println!` and the total effect is that the string is printed to +the screen. Easy enough! -The line ends with a semicolon (`;`). The `;` indicates that this expression is +We end the line with a semicolon `;`, which indicates that this expression is over, and the next one is ready to begin. Most lines of Rust code end with a `;`. ### Compiling and Running Are Separate Steps -In the “Writing and Running a Rust Program” section, we showed you how to run a -newly created program. We’ll break that process down and examine each step now. +You've just seen how to run a newly created program, so now let's break that +process down and examine each step. -Before running a Rust program, you have to compile it. You can use the Rust -compiler by entering the `rustc` command and passing it the name of your source -file, like this: +Before running a Rust program, you have to compile it using the Rust compiler +by entering the `rustc` command and passing it the name of your source file, +like this: ```text $ rustc main.rs @@ -213,30 +213,29 @@ hand, they need to have a Ruby, Python, or JavaScript implementation installed program. Everything is a tradeoff in language design. 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 your project has and -make it easy to share your code with other people and projects. Next, we’ll -introduce you to a tool called Cargo, which will help you write real-world Rust -programs. +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, and Rustaceans use Cargo to -manage their Rust projects because it makes a lot of tasks easier. For example, -Cargo takes care of building your code, downloading the libraries your code -depends on, and building those libraries. We call libraries your code needs -*dependencies*. +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 right now, you’d only be using the part of Cargo that can take -care of building your code. As you write more complex Rust programs, you’ll -want to add dependencies, and if you start off using Cargo, that will be a lot -easier to do. +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, we will assume that -you’re using it for the rest of the book. 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 typing the following into your terminal: +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 @@ -249,41 +248,39 @@ 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 -project in `hello_world`. Go back to your projects directory (or wherever you -decided to put your code): - -Linux, Mac, and PowerShell: - -```text -$ cd ~/projects -``` - -CMD for Windows: - -```cmd -> cd \d "%USERPROFILE%\projects" -``` - -And then on any operating system run: +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 ``` -We passed the `--bin` argument to `cargo new` because our goal is to make an -executable application, as opposed to a library. Executables are binary -executable files often called just *binaries*. We’ve given `hello_cargo` as the -name for our project, and Cargo creates its files in a directory of the same -name that we can then go into. + + -If we list the files in the *hello_cargo* directory, we can 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 in the *hello_cargo* directory for us, along with a *.gitignore* -file. 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. +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: @@ -303,7 +300,7 @@ authors = ["Your Name "] new` This file is in the [*TOML*][toml] (Tom’s Obvious, Minimal -Language) format. TOML is used as Cargo’s configuration format. +Language) format, which is what Cargo uses as its configuration format. [toml]: https://github.com/toml-lang/toml @@ -311,19 +308,17 @@ 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 three bits of configuration that Cargo needs to -see in order to know that it should compile your program: its name, what -version it is, and who wrote it. Cargo gets your name and email information -from your environment. If it’s not correct, go ahead and fix that and save the -file. +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 -*crates* (which is what we call packages of Rust code) that your project will -depend on so that Cargo knows to download and compile those too. We won’t need -any other crates for this project, but we will in the guessing game tutorial in -Chapter 2. +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 let’s look at *src/main.rs*: +Now open up *src/main.rs* and take a look: Filename: src/main.rs @@ -334,11 +329,9 @@ fn main() { ``` Cargo has generated a “Hello World!” for you, just like the one we wrote in -Listing 1-1! So that part is the same. The differences between our previous -project and the project generated by Cargo that we’ve seen so far are: - -- Our code goes in the *src* directory -- The top level contains a *Cargo.toml* configuration file +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, @@ -348,13 +341,14 @@ 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 your code into the *src* directory and creating an appropriate -*Cargo.toml*. +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! To do so, enter the following commands: +program through Cargo! From your project directory, build your project by +entering the following commands: ```text $ cargo build @@ -372,16 +366,15 @@ 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*. Cargo uses *Cargo.lock* to keep track of -the exact versions of dependencies used to build 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. +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: +then run all in one go: ```text $ cargo run @@ -393,8 +386,7 @@ 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: +rebuilt the project before running it, and you would have seen output like this: ```text $ cargo run @@ -404,8 +396,8 @@ $ cargo run Hello, world! ``` -Finally, there’s `cargo check`. This will quickly check your code to make sure -that it compiles, but not bother producing an executable: +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 @@ -414,20 +406,20 @@ $ cargo check ``` Why would you not want an executable? `cargo check` is often much faster than -`cargo build`, because Cargo can skip the entire step of producing the -executable. If we’re checking our work throughout the process of writing the -code, this will speed things up! As such, many Rustaceans run `cargo check` 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. +`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 a few more differences we’ve now seen: +So to recap, using Cargo: -- Instead of using `rustc`, build a project using `cargo build` or - `cargo check` (or build and run it in one step with `cargo run`). +- 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. -The other advantage of using Cargo is that the commands are the same no matter +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. @@ -439,24 +431,22 @@ 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 and that -we want to 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*. +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. With Cargo, you can just run `cargo build`, and it should work the -right way. +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, you can get -started with virtually all Rust projects you want to work on with the following -commands to check out the code using Git, change into the project directory, -and build: +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 @@ -464,7 +454,31 @@ $ cd someproject $ cargo build ``` -If you want to look at Cargo in more detail, check out [its documentation], -which covers all of its features. +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-how-rust-is-made-and-nightly-rust.md b/second-edition/src/ch01-03-how-rust-is-made-and-nightly-rust.md deleted file mode 100644 index d5c3ec86b..000000000 --- a/second-edition/src/ch01-03-how-rust-is-made-and-nightly-rust.md +++ /dev/null @@ -1,226 +0,0 @@ -## How Rust is Made and “Nightly Rust” - -Before we dive into the language itself, we’d like to finish up the -introductory chapter by talking about how Rust is made, and how that affects -you as a Rust developer. We mentioned in the “Installation” section that the -output in this book was generated by stable Rust 1.21.0, but any examples that -compile should continue to compile in any stable version of Rust greater than -that. This section is to explain how we ensure this is true! - -### Stability Without Stagnation - -As a language, Rust cares a *lot* about the stability of your code. We want -Rust to be a rock-solid foundation you can build on, and if things were -constantly changing, that would be impossible. At the same time, if we can’t -experiment with new features, we may not find out important flaws until after -their release, when we can no longer change things. - -Our solution to this problem is what we call “stability without stagnation” and -is the way we can change and improve Rust while making sure that using Rust -stays nice, stable, and boring. - -Our guiding principle for Rust releases is this: you should never have to fear -upgrading to a new version of stable Rust. Each upgrade should be painless. At -the same time, the upgrade should bring you new features, fewer bugs, and -faster compile times. - -### Choo, Choo! Release Channels and Riding the Trains - -Rust development operates on a *train schedule*. That is, all development is -done on the `master` branch of the Rust repository. Releases follow a software -release train model, which has been used by Cisco IOS and other software -projects. There are three *release channels* for Rust: - -* Nightly -* Beta -* Stable - -Most Rust developers primarily use the stable channel, but those who want to -try out experimental new features may use nightly or beta. - -Here’s an example of how the development and release process works: let’s -assume that the Rust team is working on the release of Rust 1.5. That release -happened in December of 2015, but it will provide us with realistic version -numbers. A new feature is added to Rust: a new commit lands on the `master` -branch. Each night, a new nightly version of Rust is produced. Every day is a -release day, and these releases are created by our release infrastructure -automatically. So as time passes, our releases look like this, once a night: - -```text -nightly: * - - * - - * -``` - -Every six weeks, it’s time to prepare a new release! The `beta` branch of the -Rust repository branches off from the `master` branch used by nightly. Now, -there are two releases: - -```text -nightly: * - - * - - * - | -beta: * -``` - -Most Rust users do not use beta releases actively, but test against beta in -their CI system to help Rust discover possible regressions. In the meantime, -there’s still a nightly release every night: - -```text -nightly: * - - * - - * - - * - - * - | -beta: * -``` - -Let’s say a regression is found. Good thing we had some time to test the beta -release before the regression snuck into a stable release! The fix is applied -to `master`, so that nightly is fixed, and then the fix is backported to the -`beta` branch, and a new release of beta is produced: - -```text -nightly: * - - * - - * - - * - - * - - * - | -beta: * - - - - - - - - * -``` - -Six weeks after the first beta was created, it’s time for a stable release! The -`stable` branch is produced from the `beta` branch: - -```text -nightly: * - - * - - * - - * - - * - - * - * - * - | -beta: * - - - - - - - - * - | -stable: * -``` - -Hooray! Rust 1.5 is done! However, we’ve forgotten one thing: because the six -weeks have gone by, we also need a new beta of the *next* version of Rust, 1.6. -So after `stable` branches off of `beta`, the next version of `beta` branches -off of `nightly` again: - -```text -nightly: * - - * - - * - - * - - * - - * - * - * - | | -beta: * - - - - - - - - * * - | -stable: * -``` - -This is called the “train model” because every six weeks, a release “leaves the -station”, but still has to take a journey through the beta channel before it -arrives as a stable release. - -Rust releases every six weeks, like clockwork. If you know the date of one Rust -release, you can know the date of the next one: it’s six weeks later. A nice -aspect of having releases scheduled every six weeks is that the next train is -coming soon. If a feature happens to miss a particular release, there’s no need -to worry: another one is happening in a short time! This helps reduce pressure -to sneak possibly unpolished features in close to the release deadline. - -Thanks to this process, you can always check out the next build of Rust and -verify for yourself that it’s easy to upgrade to: if a beta release doesn’t -work as expected, you can report it to the team and get it fixed before the -next stable release happens! Breakage in a beta release is relatively rare, but -`rustc` is still a piece of software, and bugs do exist. - -### Unstable Features - -There’s one more catch with this release model: unstable features. Rust uses a -technique called “feature flags” to determine what features are enabled in a -given release. If a new feature is under active development, it lands on -`master`, and therefore, in nightly, but behind a *feature flag*. If you, as a -user, wish to try out the work-in-progress feature, you can, but you must be -using a nightly release of Rust and annotate your source code with the -appropriate flag to opt in. - -If you’re using a beta or stable release of Rust, you can’t use any feature -flags. This is the key that allows us to get practical use with new features -before we declare them stable forever. Those who wish to opt into the bleeding -edge can do so, and those who want a rock-solid experience can stick with -stable and know that their code won’t break. Stability without stagnation. - -This book only contains information about stable features, as in-progress -features are still changing, and surely they’ll be different between when this -book was written and when they get enabled in stable builds. You can find -documentation for nightly-only features online. - -### Rustup and the Role of Rust Nightly - -Rustup makes it easy to change between different release channels of Rust, on a -global or per-project basis. By default, you’ll have stable Rust installed. To -install nightly, for example: - -```text -$ rustup install nightly -``` - -You can see all of the *toolchains* (releases of Rust and associated -components) you have installed with `rustup` as well. Here’s an example on one -of your authors’ computers: - -```powershell -> rustup toolchain list -stable-x86_64-pc-windows-msvc (default) -beta-x86_64-pc-windows-msvc -nightly-x86_64-pc-windows-msvc -``` - -As you can see, the stable toolchain is the default. Most Rust users use stable -most of the time. You might want to use stable most of the time, but use -nightly on a specific project, because you care about a cutting-edge feature. -To do so, you can use `rustup override` in that project’s directory to set the -nightly toolchain as the one `rustup` should use when you’re in that directory: - -```text -$ cd ~/projects/needs-nightly -$ rustup override add nightly -``` - -Now, every time you call `rustc` or `cargo` inside of -*~/projects/needs-nightly*, `rustup` will make sure that you are using nightly -Rust, rather than your default of stable Rust. This comes in handy when you -have a lot of Rust projects! - -### The RFC Process and Teams - -So how do you learn about these new features? Rust’s development model follows -a *Request For Comments (RFC) process*. If you’d like an improvement in Rust, -you can write up a proposal, called an RFC. - -Anyone can write RFCs to improve Rust, and the proposals are reviewed and -discussed by the Rust team, which is comprised of many topic subteams. There’s -a full list of the teams [on Rust’s -website](https://www.rust-lang.org/en-US/team.html), which includes teams for -each area of the project: language design, compiler implementation, -infrastructure, documentation, and more. The appropriate team reads the -proposal and the comments, writes some comments of their own, and eventually, -there’s consensus to accept or reject the feature. - -If the feature is accepted, an issue is opened on the Rust repository, and -someone can implement it. The person who implements it very well may not be the -person who proposed the feature in the first place! When the implementation is -ready, it lands on the `master` branch behind a feature gate, as we discussed -in the “Unstable Features” section. - -After some time, once Rust developers who use nightly releases have been able -to try out the new feature, team members will discuss the feature, how it’s -worked out on nightly, and decide if it should make it into stable Rust or not. -If the decision is to move forward, the feature gate is removed, and the -feature is now considered stable! It rides the trains into a new stable release -of Rust. - -## Summary - -You’re already off to a great start on your Rust journey! In this chapter, -you’ve: - -* Learned what makes Rust unique -* Installed the latest stable version of Rust -* Written a “Hello, world!” program using both `rustc` directly and using - the conventions of `cargo` -* Found out about how Rust is developed - -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. - From 3bac2f0c8feddbd772a8ae57e2bc8ec95882985c Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Mon, 19 Feb 2018 14:09:53 -0500 Subject: [PATCH 05/10] 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. From df6e414279b07051ffd1bf20dc50b19d521fb143 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Mon, 19 Feb 2018 14:13:45 -0500 Subject: [PATCH 06/10] fancy quotes --- second-edition/nostarch/chapter01.md | 32 +++++++++---------- second-edition/src/ch01-00-getting-started.md | 6 ++-- second-edition/src/ch01-01-installation.md | 12 +++---- second-edition/src/ch01-02-hello-world.md | 6 ++-- second-edition/src/ch01-03-hello-cargo.md | 8 ++--- 5 files changed, 32 insertions(+), 32 deletions(-) diff --git a/second-edition/nostarch/chapter01.md b/second-edition/nostarch/chapter01.md index eb54d215b..e6dde85ce 100644 --- a/second-edition/nostarch/chapter01.md +++ b/second-edition/nostarch/chapter01.md @@ -8,17 +8,17 @@ with some other introductory text for the chapter here? Maybe just lay out what's in this chapter so they know it's important not to skip it. --> -Let's get your Rust journey started! In this chapter, we'll discuss: +Let’s get your Rust journey started! In this chapter, we’ll discuss: - Installing Rust on Linux, Mac, or Windows -- Writing a program that prints "Hello, world!" -- Using `cargo`, Rust's package manager and build system +- Writing a program that prints “Hello, world!” +- Using `cargo`, Rust’s package manager and build system ## Installation -The first step to using Rust is to install it. We'll download Rust through +The first step to using Rust is to install it. We’ll download Rust through `rustup`, a command-line tool for managing Rust versions and associated tools. -For this you'll need an internet connection. +For this you’ll need an internet connection. The following steps will install the latest stable version of the Rust compiler. The examples and output shown in this book all use stable Rust @@ -83,9 +83,9 @@ Alternatively, you can add the following line to your `~/.bash_profile`: $ export PATH="$HOME/.cargo/bin:$PATH" ``` -Finally, you’ll need a linker of some kind. It's likely you already have one +Finally, you’ll need a linker of some kind. It’s likely you already have one installed, but if you try to compile a Rust program and get errors telling you -that a linker could not be executed, you'll need to install one. You can +that a linker could not be executed, you’ll need to install one. You can install a C compiler, as that will usually come with the correct linker. Check your platform’s documentation for how to install a C compiler. Some common Rust packages depend on C code and will need a C compiler too, so it may be worth @@ -94,7 +94,7 @@ installing one now regardless. ### Installing Rustup on Windows On Windows, go to *https://www.rust-lang.org/en-US/install.html* and follow the -instructions for installing Rust. At some point in the installation you'll +instructions for installing Rust. At some point in the installation you’ll receive a message telling you you’ll also need the C++ build tools for Visual Studio 2013 or later. The easiest way to acquire the build tools is to install Build Tools for Visual Studio 2017 at @@ -144,7 +144,7 @@ If you see this, Rust has been installed successfully! Congrats! If you don’t and you’re on Windows, check that Rust is in your `%PATH%` system variable. -If that's all correct and Rust still isn’t working, there are a number of +If that’s all correct and Rust still isn’t working, there are a number of places you can get help. The easiest is the #rust IRC channel on irc.mozilla.org, which you can access through Mibbit at *http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust*. Go to that @@ -167,7 +167,7 @@ Interface) documentation to find out! Now that you have Rust installed, let’s write your first Rust program. It’s traditional when learning a new language to write a little program to print the -text “Hello, world!” to the screen, so we'll do the same here! +text “Hello, world!” to the screen, so we’ll do the same here! > Note: This book assumes basic familiarity with the command line. Rust itself > makes no specific demands about your editing, tooling, or where your code @@ -252,7 +252,7 @@ Hello, world! ``` Regardless of your operating system, you should see the string `Hello, world!` -print to the terminal. If you don't see this output, see the "Troubleshooting" +print to the terminal. If you don’t see this output, see the “Troubleshooting” section earlier for ways to get help. If you did see `Hello, world!` printed, then congratulations! You’ve officially @@ -325,7 +325,7 @@ over, and the next one is ready to begin. Most lines of Rust code end with a ### Compiling and Running Are Separate Steps -You've just seen how to run a newly created program, so now let's break that +You’ve just seen how to run a newly created program, so now let’s break that process down and examine each step. Before running a Rust program, you have to compile it using the Rust compiler @@ -397,7 +397,7 @@ 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 +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: @@ -473,12 +473,12 @@ 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. +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 +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. +first project in Chapter 2, so we’ll use this dependencies section then. Now open up *src/main.rs* and take a look: diff --git a/second-edition/src/ch01-00-getting-started.md b/second-edition/src/ch01-00-getting-started.md index 8c13b60fc..e302171c4 100644 --- a/second-edition/src/ch01-00-getting-started.md +++ b/second-edition/src/ch01-00-getting-started.md @@ -5,8 +5,8 @@ with some other introductory text for the chapter here? Maybe just lay out what's in this chapter so they know it's important not to skip it. --> -Let's get your Rust journey started! In this chapter, we'll discuss: +Let’s get your Rust journey started! In this chapter, we’ll discuss: - Installing Rust on Linux, Mac, or Windows -- Writing a program that prints "Hello, world!" -- Using `cargo`, Rust's package manager and build system +- Writing a program that prints “Hello, world!” +- Using `cargo`, Rust’s package manager and build system diff --git a/second-edition/src/ch01-01-installation.md b/second-edition/src/ch01-01-installation.md index 299cb29d4..2922c872f 100644 --- a/second-edition/src/ch01-01-installation.md +++ b/second-edition/src/ch01-01-installation.md @@ -1,8 +1,8 @@ ## Installation -The first step to using Rust is to install it. We'll download Rust through +The first step to using Rust is to install it. We’ll download Rust through `rustup`, a command-line tool for managing Rust versions and associated tools. -For this you'll need an internet connection. +For this you’ll need an internet connection. The following steps will install the latest stable version of the Rust compiler. The examples and output shown in this book all use stable Rust @@ -67,9 +67,9 @@ Alternatively, you can add the following line to your `~/.bash_profile`: $ export PATH="$HOME/.cargo/bin:$PATH" ``` -Finally, you’ll need a linker of some kind. It's likely you already have one +Finally, you’ll need a linker of some kind. It’s likely you already have one installed, but if you try to compile a Rust program and get errors telling you -that a linker could not be executed, you'll need to install one. You can +that a linker could not be executed, you’ll need to install one. You can install a C compiler, as that will usually come with the correct linker. Check your platform’s documentation for how to install a C compiler. Some common Rust packages depend on C code and will need a C compiler too, so it may be worth @@ -79,7 +79,7 @@ installing one now regardless. On Windows, go to [https://www.rust-lang.org/en-US/install.html][install] and follow the instructions for installing Rust. At some point in the installation -you'll receive a message telling you you’ll also need the C++ build tools for +you’ll receive a message telling you you’ll also need the C++ build tools for Visual Studio 2013 or later. The easiest way to acquire the build tools is to install [Build Tools for Visual Studio 2017][visualstudio], found in the Other Tools and Frameworks section. @@ -130,7 +130,7 @@ If you see this, Rust has been installed successfully! Congrats! If you don’t and you’re on Windows, check that Rust is in your `%PATH%` system variable. -If that's all correct and Rust still isn’t working, there are a number of +If that’s all correct and Rust still isn’t working, there are a number of places you can get help. The easiest is [the #rust IRC channel on irc.mozilla.org][irc], which you can access through [Mibbit][mibbit]. Go to that address, and you’ll be chatting with other diff --git a/second-edition/src/ch01-02-hello-world.md b/second-edition/src/ch01-02-hello-world.md index 279a6a3ae..aa862373f 100644 --- a/second-edition/src/ch01-02-hello-world.md +++ b/second-edition/src/ch01-02-hello-world.md @@ -2,7 +2,7 @@ Now that you have Rust installed, let’s write your first Rust program. It’s traditional when learning a new language to write a little program to print the -text “Hello, world!” to the screen, so we'll do the same here! +text “Hello, world!” to the screen, so we’ll do the same here! > Note: This book assumes basic familiarity with the command line. Rust itself > makes no specific demands about your editing, tooling, or where your code @@ -87,7 +87,7 @@ Hello, world! ``` Regardless of your operating system, you should see the string `Hello, world!` -print to the terminal. If you don't see this output, see the "Troubleshooting" +print to the terminal. If you don’t see this output, see the “Troubleshooting” section earlier for ways to get help. If you did see `Hello, world!` printed, then congratulations! You’ve officially @@ -160,7 +160,7 @@ over, and the next one is ready to begin. Most lines of Rust code end with a ### Compiling and Running Are Separate Steps -You've just seen how to run a newly created program, so now let's break that +You’ve just seen how to run a newly created program, so now let’s break that process down and examine each step. Before running a Rust program, you have to compile it using the Rust compiler diff --git a/second-edition/src/ch01-03-hello-cargo.md b/second-edition/src/ch01-03-hello-cargo.md index 6c604eb65..d6aef269f 100644 --- a/second-edition/src/ch01-03-hello-cargo.md +++ b/second-edition/src/ch01-03-hello-cargo.md @@ -13,7 +13,7 @@ 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 +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: @@ -92,12 +92,12 @@ 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. +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 +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. +first project in Chapter 2, so we’ll use this dependencies section then. Now open up *src/main.rs* and take a look: From 29a177f7b2346ddc5d93ce50f438b407fbecd3e7 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Mon, 19 Feb 2018 14:50:22 -0500 Subject: [PATCH 07/10] spellingz --- second-edition/nostarch/chapter01.md | 6 +++--- second-edition/src/ch01-02-hello-world.md | 2 +- second-edition/src/ch01-03-hello-cargo.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/second-edition/nostarch/chapter01.md b/second-edition/nostarch/chapter01.md index e6dde85ce..47772d23f 100644 --- a/second-edition/nostarch/chapter01.md +++ b/second-edition/nostarch/chapter01.md @@ -302,7 +302,7 @@ This line does all of the work in this little program: it prints text to the screen. There are a number of details to notice here. The first is that Rust style is to indent with four spaces, not a tab. -The second important deatil is the `println!` call. This code is calling a Rust +The second important detail is the `println!` call. This code is calling a Rust *macro*. If it were calling a function instead, it would be entered as `println` (without the `!`). We’ll discuss Rust macros in more detail in Appendix D, but for now you just need to know that when you see a `!` that @@ -569,7 +569,7 @@ $ cargo check 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 +you’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. @@ -621,7 +621,7 @@ If you want to look at Cargo in more detail, check out its documentation at