From a548e8185a945e993e58f4cacf116943907cd29e Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Wed, 25 Jun 2014 16:09:45 -0400 Subject: [PATCH 01/17] Guide: Hello, cargo --- src/doc/guide.md | 113 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) diff --git a/src/doc/guide.md b/src/doc/guide.md index 19523767ae725..f7d1fad1fae34 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -264,26 +264,139 @@ projects. ## Hello, Cargo! +[Cargo](http://crates.io) is a tool that Rustaceans use to help manage their +Rust projects. Cargo is currently in an alpha state, just like Rust, and so it +is still a work in progress. However, it is already good enough to use for many +Rust projects, and so it is assumed that Rust projects will use Cargo from the +beginning. +Programmers love car analogies, so I've got a good one for you to think about +the relationship between `cargo` and `rustc`: `rustc` is like a car, and +`cargo` is like a robotic driver. You can drive your car yourself, of course, +but isn't it just easier to let a computer drive it for you? +Anyway, Cargo manages three things: building your code, downloading the +dependencies your code needs, and building the dependencies your code needs. +At first, your program doesn't have any dependencies, so we'll only be using +the first part of its functionality. Eventually, we'll add more. Since we +started off by using Cargo, it'll be easy to add later. +Let's convert Hello World to Cargo. The first thing we need to do is install +it. To do this, we need to build it from source. There are no binaries yet. +First, let's go back to our projects directory. We don't want Cargo to +live in our project! +```{bash} +$ cd .. +``` + +Next, we need these commands: + +```{bash} +$ git clone --recursive https://github.com/rust-lang/cargo +$ cd cargo +$ make +$ make install # may need sudo or admin permissions +``` + +The `--recursive` downloads Cargo's own dependencies. You can't use Cargo to +fetch dependencies until you have Cargo installed! + +Let's see if that worked. Try this: + +```{bash} +$ cargo +Commands: + build # compile the current project + +Options (for all commands): + +-v, [--verbose] +-h, [--help] +``` + +If you see this output when you run `cargo`, congrats! Cargo is working. If +not, please [open an Issue](https://github.com/rust-lang/cargo/issues/new) or +drop by the Rust IRC, and we can help you out. +Let's move back into our `hello_world` directory now: +```{bash} +$ cd .. # move back up into projects +$ cd hello_world # move into hello_world +``` + +To Cargo-ify our project, we need to do two things: Make a `Cargo.toml` +configuration file, and put our source file in the right place. Let's +do that part first: + +```{bash} +$ mkdir src +$ mv hello_world.rs src/hello_world.rs +``` + +Cargo expects your source files to live inside a `src` directory. That leaves +the top level for other things, like READMEs, licence information, and anything +not related to your code. Cargo helps us keep our projects nice and tidy. A +place for everything, and everything in its place. +Next, our configuration file: +```{bash} +$ editor Cargo.toml +``` +Make sure to get this name right: you need the capital `C`! +Put this inside: +``` +[package] +name = "hello_world" +version = "0.1.0" +authors = [ "someone@example.com" ] +[[bin]] +name = "hello_world" +``` +This file is in the [TOML](https://github.com/toml-lang/toml) format. Let's let +it explain itself to you: +> TOML aims to be a minimal configuration file format that's easy to read due +> to obvious semantics. TOML is designed to map unambiguously to a hash table. +> TOML should be easy to parse into data structures in a wide variety of +> languages. +TOML is very similar to INI, but with some extra goodies. +Anyway, there are two **table**s in this file: `package` and `bin`. The first +tells Cargo metadata about your package. The second tells Cargo that we're +interested in building a binary, not a library (though we could do both!), as +well as what it is named. +Once you have this file in place, we should be ready to build! Try this: + +```{bash} +$ cargo build + Compiling hello_world v0.1.0 (file:/home/yourname/projects/hello_world) +$ ./target/hello_world +Hello, world! +``` +Bam! We build our project with `cargo build`, and run it with +`./target/hello_world`. This hasn't bought us a whole lot over our simple use +of `rustc`, but think about the future: when our project has more tha one file, +we would need to call `rustc` twice, and pass it a bunch of options to tell it +to build everything together. With Cargo, as our project grows, we can just +`cargo build` and it'll work the right way. +That's it! We've successfully built `hello_world` with Cargo. Even though our +program is simple, it's using all of the real tooling that you'll use for the +rest of your Rust career. +Next, we'll learn more about Rust itself, by starting to write a more complicated +program. We hope you want to do more with Rust than just print "Hello, world!" From 39549bebf0f4bcbc9fe5a67affe4d9ae00f6993f Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:30:06 -0400 Subject: [PATCH 02/17] Add a note that this requires `git`. --- src/doc/guide.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index f7d1fad1fae34..d295a8a6b5da0 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -301,7 +301,14 @@ $ make install # may need sudo or admin permissions ``` The `--recursive` downloads Cargo's own dependencies. You can't use Cargo to -fetch dependencies until you have Cargo installed! +fetch dependencies until you have Cargo installed! Also, you will need to have +`git` installed. Much of the Rust world assumes `git` usage, so it's a good +thing to have around. Please check out [the git +documentation](http://git-scm.com/book/en/Getting-Started-Installing-Git) for +more on installing `git`. + +We hope to give Cargo a binary installer, similar to Rust's own, so that +this will not be necessary in the future. Let's see if that worked. Try this: From fb594484e6b290f95efc8a6108b6e9892a3016bc Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:30:44 -0400 Subject: [PATCH 03/17] Fix capitalization of Issue. @chris-morgan and @huonw pointed out that even though the feature is a proper noun, we're using it in a more generic sense here. --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index d295a8a6b5da0..deaeec01e855c 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -324,7 +324,7 @@ Options (for all commands): ``` If you see this output when you run `cargo`, congrats! Cargo is working. If -not, please [open an Issue](https://github.com/rust-lang/cargo/issues/new) or +not, please [open an issue](https://github.com/rust-lang/cargo/issues/new) or drop by the Rust IRC, and we can help you out. Let's move back into our `hello_world` directory now: From 98fd2abe0a8cecf26c6ae21d13c8a192fbdbf85d Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:31:41 -0400 Subject: [PATCH 04/17] tha -> than Thanks @huonw :heart: --- src/doc/guide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index deaeec01e855c..a7df8b697ed6b 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -396,10 +396,10 @@ Hello, world! Bam! We build our project with `cargo build`, and run it with `./target/hello_world`. This hasn't bought us a whole lot over our simple use -of `rustc`, but think about the future: when our project has more tha one file, -we would need to call `rustc` twice, and pass it a bunch of options to tell it -to build everything together. With Cargo, as our project grows, we can just -`cargo build` and it'll work the right way. +of `rustc`, but think about the future: when our project has more than one +file, we would need to call `rustc` twice, and pass it a bunch of options to +tell it to build everything together. With Cargo, as our project grows, we can +just `cargo build` and it'll work the right way. That's it! We've successfully built `hello_world` with Cargo. Even though our program is simple, it's using all of the real tooling that you'll use for the From 8fd69c4009f8cb00e6e748f5c576ead0ea5ac7c8 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:32:35 -0400 Subject: [PATCH 05/17] all/some How could I forsake `rustdoc`? :sweat_smile: Thanks @huonw. --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index a7df8b697ed6b..91fd6253024f6 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -402,7 +402,7 @@ tell it to build everything together. With Cargo, as our project grows, we can just `cargo build` and it'll work the right way. That's it! We've successfully built `hello_world` with Cargo. Even though our -program is simple, it's using all of the real tooling that you'll use for the +program is simple, it's using much of the real tooling that you'll use for the rest of your Rust career. Next, we'll learn more about Rust itself, by starting to write a more complicated From 00ae6484960ec598370810c821bfdf4593453b37 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:34:15 -0400 Subject: [PATCH 06/17] staticly -> statically What's funny about this one is that spellcheck caught it, but for some reason didn't give me the right suggestion, so I assumed that it wasn't in my dictionary. Oh well. Thanks @P1start! :heart: --- src/doc/guide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 91fd6253024f6..8a2f0d0ab2fa6 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -201,11 +201,11 @@ would look like this: `println()`. For our purposes, we don't need to worry about this difference. Just know that sometimes, you'll see a `!`, and that means that you're calling a macro instead of a normal function. -Next, `"Hello, world"` is a **string**. Strings are a surprisingly -complicated topic in a systems programming language, and this is a **staticly -allocated** string. We will talk more about different kinds of allocation -later. We pass this string as an argument to `println!`, which prints the -string to the screen. Easy enough! +Next, `"Hello, world"` is a **string**. Strings are a surprisingly complicated +topic in a systems programming language, and this is a **statically allocated** +string. We will talk more about different kinds of allocation later. We pass +this string as an argument to `println!`, which prints the string to the +screen. Easy enough! Finally, the line ends with a semicolon (`;`). Rust is an **expression oriented** language, which means that most things are expressions. The `;` is From 08f533481d22c3058c82eeff53a5e08f0d03f9ce Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:35:56 -0400 Subject: [PATCH 07/17] Fix IRC linkage. Death to `here`! Thanks @chris-morgan :heart: --- src/doc/guide.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 8a2f0d0ab2fa6..42a169c2f4ac0 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -96,8 +96,9 @@ host: x86_64-unknown-linux-gnu If you did, Rust has been installed successfully! Congrats! If not, there are a number of places where you can get help. The easiest is -IRC, which you can access -[here](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust). Click +[the #rust IRC channel on irc.mozilla.org](irc://irc.mozilla.org/#rust), which +you can access through +[Mibbit](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust). Click that link, and you'll be chatting with other Rustaceans (a silly nickname we call ourselves), and we can help you out. Other great resources include our [mailing list](https://mail.mozilla.org/listinfo/rust-dev), From 49a9959d8c3625eae4c6d79ffffec1ac3def253e Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:36:57 -0400 Subject: [PATCH 08/17] StackOverflow -> Stack Overflow Thanks @chris-morgan --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 42a169c2f4ac0..39771791c50b7 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -103,7 +103,7 @@ that link, and you'll be chatting with other Rustaceans (a silly nickname we call ourselves), and we can help you out. Other great resources include our [mailing list](https://mail.mozilla.org/listinfo/rust-dev), [subreddit](http://www.reddit.com/r/rust), and -[StackOverflow](http://stackoverflow.com/questions/tagged/rust). +[Stack Overflow](http://stackoverflow.com/questions/tagged/rust). ## Hello, world! From af4a6c30aa2659af59c8d5418f3f5c04abd26148 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:37:57 -0400 Subject: [PATCH 09/17] Fixing link to subreddit. Thanks @chris-morgan :heart: --- src/doc/guide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 39771791c50b7..2e4ec8fe88346 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -100,10 +100,10 @@ If not, there are a number of places where you can get help. The easiest is you can access through [Mibbit](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust). Click that link, and you'll be chatting with other Rustaceans (a silly nickname we -call ourselves), and we can help you out. Other great resources include our -[mailing list](https://mail.mozilla.org/listinfo/rust-dev), -[subreddit](http://www.reddit.com/r/rust), and -[Stack Overflow](http://stackoverflow.com/questions/tagged/rust). +call ourselves), and we can help you out. Other great resources include [our +mailing list](https://mail.mozilla.org/listinfo/rust-dev), [the /r/rust +subreddit](http://www.reddit.com/r/rust), and [Stack +Overflow](http://stackoverflow.com/questions/tagged/rust). ## Hello, world! From c73f17486a0101121df8d0c8f89f2fdffd72e70f Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:39:30 -0400 Subject: [PATCH 10/17] Move note about $ up Thanks @chris-morgan :heart: --- src/doc/guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 2e4ec8fe88346..9a995de582e98 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -27,7 +27,8 @@ Sound good? Let's go! The first step to using Rust is to install it! There are a number of ways to install Rust, but the easiest is to use the the `rustup` script. If you're on -Linux or a Mac, All you need to do is this: +Linux or a Mac, all you need to do is this (note that you don't need to type +in the `$`s, they just indicate the start of each command): ```{ignore} $ curl -s http://www.rust-lang.org/rustup.sh | sudo sh @@ -124,8 +125,7 @@ require that you know a whole ton about the command line, but until the language is in a more finished state, IDE support is spotty. Rust makes no specific demands on your editing tooling, or where your code lives. -With that said, let's make a directory in our projects directory. Note that you -don't need to type in the `$`s, they just indicate the start of each command: +With that said, let's make a directory in our projects directory. ```{bash} $ mkdir ~/projects From efc2d4a476f8c0d4ed0d67bd496187ed76a55172 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:40:52 -0400 Subject: [PATCH 11/17] TIL PATHEXT Thanks @chris-morgan :heart: --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 9a995de582e98..f7b100d6b05e4 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -160,7 +160,7 @@ Save the file, and then type this into your terminal window: ```{bash} $ rustc hello_world.rs -$ ./hello_world # on Windows, this is ./hello_world.exe +$ ./hello_world Hello, world ``` From 8cd906811a1f541772fd526fc61ff2b6ead86f2e Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:41:46 -0400 Subject: [PATCH 12/17] Clarify which curly is being referred to Thanks @chris-morgan --- src/doc/guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index f7b100d6b05e4..b3ae6db806113 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -181,8 +181,8 @@ entirely. We'll get to it later. You'll also note that the function is wrapped in curly braces (`{` and `}`). Rust requires these around all function bodies. It is also considered good -style to put the curly brace on the same line as the function declaration, with -one space in between. +style to put the opening curly brace on the same line as the function +declaration, with one space in between. Next up is this line: From 546b202e0edbeb53a474c6126d8ad5d47081be2f Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:44:29 -0400 Subject: [PATCH 13/17] Note that macros != templates Good call, @chris-morgan and @cmr! --- src/doc/guide.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index b3ae6db806113..fabf04124baf7 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -200,7 +200,10 @@ The second point is the `println!()` part. This is calling a Rust **macro**, which is how metaprogramming is done in Rust. If it were a function instead, it would look like this: `println()`. For our purposes, we don't need to worry about this difference. Just know that sometimes, you'll see a `!`, and that -means that you're calling a macro instead of a normal function. +means that you're calling a macro instead of a normal function. One last thing +to mention: Rust's macros are significantly different than C++ templates, if +you've used those. Don't be scared of using macros. We'll get to the details +eventually, you'll just have to trust us for now. Next, `"Hello, world"` is a **string**. Strings are a surprisingly complicated topic in a systems programming language, and this is a **statically allocated** From 15bcb2f9c6232472b391638af780b3d1a91a4584 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 15:46:36 -0400 Subject: [PATCH 14/17] Fix missing word and some grammar Thanks @chris-morgan and @P1start! :heart: --- src/doc/guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index fabf04124baf7..f33398b1a4eae 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -239,8 +239,8 @@ $ dir hello_world.exe hello_world.rs ``` -There are now two files: our source code, with the `.rs`, and the executable. -We ran the executable like this: +There are now two files: our source code, with the `.rs` extension, and the +executable (`hello_world.exe` on Windows, `hello_world` everywhere else) ```{bash} $ ./hello_world # or ./hello_world.exe on Windows From e4b87077fb91fe676a2a977cd7e4d1e93e519fec Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 16:58:20 -0400 Subject: [PATCH 15/17] C macros, not C++ templates. @cmr rightfully points out that C macros are worse, and share the same name. --- src/doc/guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index f33398b1a4eae..92e054b55a191 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -201,8 +201,8 @@ which is how metaprogramming is done in Rust. If it were a function instead, it would look like this: `println()`. For our purposes, we don't need to worry about this difference. Just know that sometimes, you'll see a `!`, and that means that you're calling a macro instead of a normal function. One last thing -to mention: Rust's macros are significantly different than C++ templates, if -you've used those. Don't be scared of using macros. We'll get to the details +to mention: Rust's macros are significantly different than C macros, if you've +used those. Don't be scared of using macros. We'll get to the details eventually, you'll just have to trust us for now. Next, `"Hello, world"` is a **string**. Strings are a surprisingly complicated From aee263c6b09a53c0f1e4269a2e134451d602cec7 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 20:49:27 -0400 Subject: [PATCH 16/17] Fix windows run instructions Thank you, @stormbrew! --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 92e054b55a191..446753a1c9cc4 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -160,7 +160,7 @@ Save the file, and then type this into your terminal window: ```{bash} $ rustc hello_world.rs -$ ./hello_world +$ ./hello_world # just 'hello_world' on Windows Hello, world ``` From 6bfbc35491f320092c82a5f599963cd197bc6ca9 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Thu, 26 Jun 2014 21:57:46 -0400 Subject: [PATCH 17/17] Add one more ignore. Thanks @huonw --- src/doc/guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 446753a1c9cc4..fd7846386ed1b 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -362,7 +362,7 @@ Make sure to get this name right: you need the capital `C`! Put this inside: -``` +```{ignore} [package] name = "hello_world"