Guide: Hello, cargo
This commit is contained in:
parent
b20f968ed2
commit
a548e8185a
113
src/doc/guide.md
113
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!"
|
||||
|
|
Loading…
Reference in New Issue