write docs for targets

Author: steveklabnik

src/doc/rustc/src/targets/built-in.md

@@ -1 +1,10 @@
 # Built-in Targets
+
+`rustc` ships with the ability to compile to many targets automatically, we
+call these "built-in" targets, and they generally correspond to targets that
+the team is supporting directly.
+
+To see the list of built-in targets, you can run `rustc --print target-list`,
+or look at [the API
+docs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_back/target/#modules).
+Each module there defines a builder for a particular target.

src/doc/rustc/src/targets/custom.md

@@ -1 +1,17 @@
 # Custom Targets
+
+If you'd like to build for a target that is not yet supported by `rustc`, you can use a
+"custom target specification" to define a target. These target specification files
+are JSON. To see the JSON for the host target, you can run:
+
+```bash
+$ rustc +nightly -Z unstable-options --print target-spec-json
+```
+
+To see it for a different target, add the `--target` flag:
+
+```bash
+$ rustc +nightly -Z unstable-options --target=wasm32-unknown-unknown --print target-spec-json
+```
+
+To use a custom target, see [`xargo`](https://github.com/japaric/xargo).

src/doc/rustc/src/targets/index.md

@@ -1 +1,14 @@
 # Targets
+
+`rustc` is a cross-compiler by default. This means that you can use any compiler to build for any
+architecture. The list of *targets* are the possible architectures that you can build for.
+
+You can see the API docs for a given target
+[here](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_back/target/struct.Target.html), all
+of these options can be set on a per-target basis.
+
+To compile to a particular target, use the `--target` flag:
+
+```bash
+$ rustc src/main.rs --target=wasm32-unknown-unknown
+```