src/doc/trpl/hello-cargo.md

   1 % Hello, Cargo!
   2
   3 [Cargo](http://crates.io) is a tool that Rustaceans use to help manage their
   4 Rust projects. Cargo is currently in an alpha state, just like Rust, and so it
   5 is still a work in progress. However, it is already good enough to use for many
   6 Rust projects, and so it is assumed that Rust projects will use Cargo from the
   7 beginning.
   8
   9 Cargo manages three things: building your code, downloading the dependencies
  10 your code needs, and building those dependencies. At first, your
  11 program doesn't have any dependencies, so we'll only be using the first part of
  12 its functionality. Eventually, we'll add more. Since we started off by using
  13 Cargo, it'll be easy to add later.
  14
  15 If you installed Rust via the official installers you will also have
  16 Cargo. If you installed Rust some other way, you may want to [check
  17 the Cargo
  18 README](https://github.com/rust-lang/cargo#installing-cargo-from-nightlies)
  19 for specific instructions about installing it.
  20
  21 Let's convert Hello World to Cargo.
  22
  23 To Cargo-ify our project, we need to do two things: Make a `Cargo.toml`
  24 configuration file, and put our source file in the right place. Let's
  25 do that part first:
  26
  27 ```{bash}
  28 $ mkdir src
  29 $ mv main.rs src/main.rs
  30 ```
  31
  32 Cargo expects your source files to live inside a `src` directory. That leaves
  33 the top level for other things, like READMEs, license information, and anything
  34 not related to your code. Cargo helps us keep our projects nice and tidy. A
  35 place for everything, and everything in its place.
  36
  37 Next, our configuration file:
  38
  39 ```{bash}
  40 $ editor Cargo.toml
  41 ```
  42
  43 Make sure to get this name right: you need the capital `C`!
  44
  45 Put this inside:
  46
  47 ```toml
  48 [package]
  49
  50 name = "hello_world"
  51 version = "0.0.1"
  52 authors = [ "Your name <you@example.com>" ]
  53
  54 [[bin]]
  55
  56 name = "hello_world"
  57 ```
  58
  59 This file is in the [TOML](https://github.com/toml-lang/toml) format. Let's let
  60 it explain itself to you:
  61
  62 > TOML aims to be a minimal configuration file format that's easy to read due
  63 > to obvious semantics. TOML is designed to map unambiguously to a hash table.
  64 > TOML should be easy to parse into data structures in a wide variety of
  65 > languages.
  66
  67 TOML is very similar to INI, but with some extra goodies.
  68
  69 Anyway, there are two *tables* in this file: `package` and `bin`. The first
  70 tells Cargo metadata about your package. The second tells Cargo that we're
  71 interested in building a binary, not a library (though we could do both!), as
  72 well as what it is named.
  73
  74 Once you have this file in place, we should be ready to build! Try this:
  75
  76 ```{bash}
  77 $ cargo build
  78    Compiling hello_world v0.0.1 (file:///home/yourname/projects/hello_world)
  79 $ ./target/hello_world
  80 Hello, world!
  81 ```
  82
  83 Bam! We build our project with `cargo build`, and run it with
  84 `./target/hello_world`. This hasn't bought us a whole lot over our simple use
  85 of `rustc`, but think about the future: when our project has more than one
  86 file, we would need to call `rustc` more than once, and pass it a bunch of options to
  87 tell it to build everything together. With Cargo, as our project grows, we can
  88 just `cargo build` and it'll work the right way.
  89
  90 You'll also notice that Cargo has created a new file: `Cargo.lock`.
  91
  92 ```toml
  93 [root]
  94 name = "hello_world"
  95 version = "0.0.1"
  96 ```
  97
  98 This file is used by Cargo to keep track of dependencies in your application.
  99 Right now, we don't have any, so it's a bit sparse. You won't ever need
 100 to touch this file yourself, just let Cargo handle it.
 101
 102 That's it! We've successfully built `hello_world` with Cargo. Even though our
 103 program is simple, it's using much of the real tooling that you'll use for the
 104 rest of your Rust career.
 105
 106 Now that you've got the tools down, let's actually learn more about the Rust
 107 language itself. These are the basics that will serve you well through the rest
 108 of your time with Rust.