src/doc/trpl/hello-cargo.md

   1 % Hello, Cargo!
   2
   3 [Cargo][cratesio] is a tool that Rustaceans use to help manage their Rust
   4 projects. Cargo is currently in a pre-1.0 state, and so it is still a work in
   5 progress. However, it is already good enough to use for many Rust projects, and
   6 so it is assumed that Rust projects will use Cargo from the beginning.
   7
   8 [cratesio]: http://doc.crates.io
   9
  10 Cargo manages three things: building our code, downloading the dependencies our
  11 code needs, and building those dependencies. At first, our program doesn’t have
  12 any dependencies, so we’ll only be using the first part of its functionality.
  13 Eventually, we’ll add more. Since we started off by using Cargo, it'll be easy
  14 to add later.
  15
  16 If you installed Rust via the official installers you will also have Cargo. If
  17 you installed Rust some other way, you may want to
  18 [check the Cargo README][cargoreadme] for specific instructions about installing
  19 it.
  20
  21 [cargoreadme]: https://github.com/rust-lang/cargo#installing-cargo-from-nightlies
  22
  23 ## Converting to Cargo
  24
  25 Let’s convert Hello World to Cargo.
  26
  27 To Cargo-ify our project, we need to do three things: Make a `Cargo.toml`
  28 configuration file, put our source file in the right place, and get rid of the
  29 old executable (`main.exe` on Windows, `main` everywhere else). Let's do that part first:
  30
  31 ```bash
  32 $ mkdir src
  33 $ mv main.rs src/main.rs
  34 $ rm main  # or 'rm main.exe' on Windows
  35 ```
  36
  37 > Note: since we're creating an executable, we retain `main.rs` as the source
  38 > filename. If we want to make a library instead, we should use `lib.rs`. This
  39 > convention is used by Cargo to successfully compile our projects, but it can
  40 > be overridden if we wish. Custom file locations for the entry point can be
  41 > specified with a [`[lib]` or `[[bin]]`][crates-custom] key in the TOML file.
  42
  43 [crates-custom]: http://doc.crates.io/manifest.html#configuring-a-target
  44
  45 Cargo expects our source files to live inside a `src` directory. That leaves the
  46 top level for other things, like READMEs, license information, and anything not
  47 related to our code. Cargo helps us keep our projects nice and tidy. A place for
  48 everything, and everything in its place.
  49
  50 Next, our configuration file:
  51
  52 ```bash
  53 $ editor Cargo.toml # or 'notepad Cargo.toml' on Windows
  54 ```
  55
  56 Make sure to get this name right: we need the capital `C`!
  57
  58 Put this inside:
  59
  60 ```toml
  61 [package]
  62
  63 name = "hello_world"
  64 version = "0.0.1"
  65 authors = [ "Your name <you@example.com>" ]
  66 ```
  67
  68 This file is in the [TOML][toml] format. TOML is similar to INI, but has some
  69 extra goodies. According to the TOML docs,
  70
  71 > TOML aims to be a minimal configuration file format that's easy to read due
  72 > to obvious semantics. TOML is designed to map unambiguously to a hash table.
  73 > TOML should be easy to parse into data structures in a wide variety of
  74 > languages.
  75
  76 [toml]: https://github.com/toml-lang/toml
  77
  78 Once we have this file in place in our project's root directory, we should be
  79 ready to build! To do so, run:
  80
  81 ```bash
  82 $ cargo build
  83    Compiling hello_world v0.0.1 (file:///home/yourname/projects/hello_world)
  84 $ ./target/debug/hello_world
  85 Hello, world!
  86 ```
  87
  88 Bam! We built our project with `cargo build`, and ran it with
  89 `./target/debug/hello_world`. We can do both in one step with `cargo run`:
  90
  91 ```bash
  92 $ cargo run
  93      Running `target/debug/hello_world`
  94 Hello, world!
  95 ```
  96
  97 Notice that we didn’t re-build the project this time. Cargo figured out that
  98 we hadn’t changed the source file, and so it just ran the binary. If we had
  99 made a modification, we would have seen it do both:
 100
 101 ```bash
 102 $ cargo run
 103    Compiling hello_world v0.0.1 (file:///home/yourname/projects/hello_world)
 104      Running `target/debug/hello_world`
 105 Hello, world!
 106 ```
 107
 108 This hasn’t bought us a whole lot over our simple use of `rustc`, but think
 109 about the future: when our project gets more complex, we need to do more
 110 things to get all of the parts to properly compile. With Cargo, as our project
 111 grows, we can just run `cargo build`, and it’ll work the right way.
 112
 113 When our project is finally ready for release, we can use `cargo build
 114 --release` to compile our project with optimizations.
 115
 116 You'll also notice that Cargo has created a new file: `Cargo.lock`.
 117
 118 ```toml
 119 [root]
 120 name = "hello_world"
 121 version = "0.0.1"
 122 ```
 123
 124 The `Cargo.lock` file is used by Cargo to keep track of dependencies in our
 125 application. Right now, we don’t have any, so it’s a bit sparse. We won't ever
 126 need to touch this file ourselves, just let Cargo handle it.
 127
 128 That’s it! We’ve successfully built `hello_world` with Cargo. Even though our
 129 program is simple, it’s using much of the real tooling that we’ll use for the
 130 rest of our Rust career. We can expect to do this to get started with virtually
 131 all Rust projects:
 132
 133 ```bash
 134 $ git clone someurl.com/foo
 135 $ cd foo
 136 $ cargo build
 137 ```
 138
 139 ## A New Project
 140
 141 We don’t have to go through this whole process every time we want to start a new
 142 project! Cargo has the ability to make a bare-bones project directory in which
 143 we can start developing right away.
 144
 145 To start a new project with Cargo, we use `cargo new`:
 146
 147 ```bash
 148 $ cargo new hello_world --bin
 149 ```
 150
 151 We’re passing `--bin` because our goal is to get straight to making an
 152 executable application, as opposed to a library. Executables are often called
 153 ‘binaries.’ (as in `/usr/bin`, if we’re on a Unix system)
 154
 155 Let's check out what Cargo has generated for us:
 156
 157 ```bash
 158 $ cd hello_world
 159 $ tree .
 160 .
 161 ├── Cargo.toml
 162 └── src
 163     └── main.rs
 164
 165 1 directory, 2 files
 166 ```
 167
 168 If we don't have the `tree` command, we can probably get it from our
 169 distribution’s package manager. It’s not necessary, but it’s certainly useful.
 170
 171 This is all we need to get started. First, let’s check out `Cargo.toml`:
 172
 173 ```toml
 174 [package]
 175
 176 name = "hello_world"
 177 version = "0.1.0"
 178 authors = ["Your Name <you@example.com>"]
 179 ```
 180
 181 Cargo has populated this file with reasonable defaults based off the arguments
 182 we gave it and our `git` global configuration. You may notice that Cargo has
 183 also initialized the `hello_world` directory as a `git` repository.
 184
 185 Here’s what’s in `src/main.rs`:
 186
 187 ```rust
 188 fn main() {
 189     println!("Hello, world!");
 190 }
 191 ```
 192
 193 Cargo has generated a "Hello World!" for us, and we’re ready to start coding!
 194 Cargo has its own [guide][guide] which covers Cargo’s features in much more
 195 depth.
 196
 197 [guide]: http://doc.crates.io/guide.html
 198
 199 Now that we’ve got the tools down, let’s actually learn more about the Rust
 200 language itself. These are the basics that will serve us well through the rest
 201 of our time with Rust.
 202
 203 You have two options: Dive into a project with ‘[Learn Rust][learnrust]’, or
 204 start from the bottom and work your way up with
 205 ‘[Syntax and Semantics][syntax]’. More experienced systems programmers will
 206 probably prefer ‘Learn Rust’, while those from dynamic backgrounds may enjoy
 207 either. Different people learn differently! Choose whatever’s right for you.
 208
 209 [learnrust]: learn-rust.html
 210 [syntax]: syntax-and-semantics.html