Add basic steps for a new target (#805)

Co-authored-by: Yuki Okushi <huyuumi.dev@gmail.com>

src/SUMMARY.md

@@ -16,6 +16,7 @@
     - [Documenting Compiler](./building/compiler-documenting.md)
     - [Rustdoc](./rustdoc.md)
     - [ctags](./building/ctags.md)
+    - [Adding a new target](./building/new-target.md)
 - [The compiler testing framework](./tests/intro.md)
     - [Running tests](./tests/running.md)
     - [Adding new tests](./tests/adding.md)

src/building/new-target.md

@@ -0,0 +1,101 @@
+# Adding a new target
+
+These are a set of steps to add support for a new target. There are
+numerous end states and paths to get there, so not all sections may be
+relevant to your desired goal.
+
+## Specifying a new LLVM
+
+For very new targets, you may need to use a different fork of LLVM
+than what is currently shipped with Rust. In that case, navigate to
+the `src/llvm_project` git submodule (you might need to run `x.py
+check` at least once so the submodule is updated), check out the
+appropriate commit for your fork, then commit that new submodule
+reference in the main Rust repository.
+
+An example would be:
+
+```
+cd src/llvm_project
+git remote add my-target-llvm some-llvm-repository
+git checkout my-target-llvm/my-branch
+cd ..
+git add llvm_target
+git commit -m 'Use my custom LLVM'
+```
+
+If you have a local LLVM checkout that is already built, you *may* be
+able to configure Rust to treat your build as the [system
+LLVM][sysllvm] to avoid redundant builds.
+
+[sysllvm]: ./suggested.md#building-with-system-llvm
+
+## Creating a target specification
+
+You should start with a target JSON file. You can see the specification
+for an existing target using `--print target-spec-json`:
+
+```
+rustc -Z unstable-options --target=wasm32-unknown-unknown --print target-spec-json
+```
+
+Save that JSON to a file and modify it as appropriate for your target.
+
+### Adding a target specification
+
+Once you have filled out a JSON specification and been able to compile
+somewhat successfully, you can copy the specification into the
+compiler itself.
+
+You will need to add a line to the big table inside of the
+`supported_targets` macro in the `librustc_target::spec` module. You
+will then add a corresponding file for your new target containing a
+`target` function.
+
+Look for existing targets to use as examples
+
+## Patching crates
+
+You may need to make changes to crates that the compiler depends on,
+such as [`libc`][] or [`cc`][]. If so, you can use Cargo's
+[`[patch]`][patch] ability. For example, if you want to use an
+unreleased version of `libc`, you can add it to the top-level
+`Cargo.toml` file:
+
+```diff
+diff --git a/Cargo.toml b/Cargo.toml
+index be15e50e2bc..4fb1248ba99 100644
+--- a/Cargo.toml
++++ b/Cargo.toml
+@@ -66,10 +66,11 @@ cargo = { path = "src/tools/cargo" }
+ [patch.crates-io]
+ # Similar to Cargo above we want the RLS to use a vendored version of `rustfmt`
+ # that we're shipping as well (to ensure that the rustfmt in RLS and the
+ # `rustfmt` executable are the same exact version).
+ rustfmt-nightly = { path = "src/tools/rustfmt" }
++libc = { git = "https://github.com/rust-lang/libc", rev = "0bf7ce340699dcbacabdf5f16a242d2219a49ee0" }
+
+ # See comments in `src/tools/rustc-workspace-hack/README.md` for what's going on
+ # here
+ rustc-workspace-hack = { path = 'src/tools/rustc-workspace-hack' }
+```
+
+After this, run `cargo update -p libc` to update the lockfiles.
+
+[`libc`]: https://crates.io/crates/libc
+[`cc`]: https://crates.io/crates/cc
+[patch]: https://doc.rust-lang.org/stable/cargo/reference/overriding-dependencies.html#the-patch-section
+
+## Cross-compiling
+
+Once you have a target specification in JSON and in the code, you can
+cross-compile `rustc`:
+
+```
+DESTDIR=/path/to/install/in \
+./x.py install -i --stage 1 --host aarch64-apple-darwin.json --target aarch64-apple-darwin \
+src/librustc src/libstd
+```
+
+If your target specification is already available in the bootstrap
+compiler, you can use it instead of the JSON file for both arguments.