src/doc/rustc/src/what-is-rustc.md

   1 # What is rustc?
   2
   3 Welcome to "The rustc book"! `rustc` is the compiler for the Rust programming
   4 language, provided by the project itself. Compilers take your source code and
   5 produce binary code, either as a library or executable.
   6
   7 Most Rust programmers don't invoke `rustc` directly, but instead do it through
   8 [Cargo](../cargo/index.html). It's all in service of `rustc` though! If you
   9 want to see how Cargo calls `rustc`, you can
  10
  11 ```bash
  12 $ cargo build --verbose
  13 ```
  14
  15 And it will print out each `rustc` invocation. This book can help you
  16 understand what each of these options does. Additionally, while most
  17 Rustaceans use Cargo, not all do: sometimes they integrate `rustc` into other
  18 build systems. This book should provide a guide to all of the options you'd
  19 need to do so.
  20
  21 ## Basic usage
  22
  23 Let's say you've got a little hello world program in a file `hello.rs`:
  24
  25 ```rust
  26 fn main() {
  27     println!("Hello, world!");
  28 }
  29 ```
  30
  31 To turn this source code into an executable, you can use `rustc`:
  32
  33 ```bash
  34 $ rustc hello.rs
  35 $ ./hello # on a *NIX
  36 $ .\hello.exe # on Windows
  37 ```
  38
  39 Note that we only ever pass `rustc` the *crate root*, not every file we wish
  40 to compile. For example, if we had a `main.rs` that looked like this:
  41
  42 ```rust,ignore (needs-multiple-files)
  43 mod foo;
  44
  45 fn main() {
  46     foo::hello();
  47 }
  48 ```
  49
  50 And a `foo.rs` that had this:
  51
  52 ```rust,no_run
  53 pub fn hello() {
  54     println!("Hello, world!");
  55 }
  56 ```
  57
  58 To compile this, we'd run this command:
  59
  60 ```bash
  61 $ rustc main.rs
  62 ```
  63
  64 No need to tell `rustc` about `foo.rs`; the `mod` statements give it
  65 everything that it needs. This is different than how you would use a C
  66 compiler, where you invoke the compiler on each file, and then link
  67 everything together. In other words, the *crate* is a translation unit, not a
  68 particular module.