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