src/doc/rustc-dev-guide/src/building/new-target.md

   1 # Adding a new target
   2
   3 These are a set of steps to add support for a new target. There are
   4 numerous end states and paths to get there, so not all sections may be
   5 relevant to your desired goal.
   6
   7 ## Specifying a new LLVM
   8
   9 For very new targets, you may need to use a different fork of LLVM
  10 than what is currently shipped with Rust. In that case, navigate to
  11 the `src/llvm-project` git submodule (you might need to run `x.py
  12 check` at least once so the submodule is updated), check out the
  13 appropriate commit for your fork, then commit that new submodule
  14 reference in the main Rust repository.
  15
  16 An example would be:
  17
  18 ```
  19 cd src/llvm-project
  20 git remote add my-target-llvm some-llvm-repository
  21 git checkout my-target-llvm/my-branch
  22 cd ..
  23 git add llvm_target
  24 git commit -m 'Use my custom LLVM'
  25 ```
  26
  27 ### Using pre-built LLVM
  28
  29 If you have a local LLVM checkout that is already built, you may be
  30 able to configure Rust to treat your build as the [system LLVM][sysllvm]
  31 to avoid redundant builds.
  32
  33 You can tell Rust to use a pre-built version of LLVM using the `target` section
  34 of `config.toml`:
  35
  36 ```toml
  37 [target.x86_64-unknown-linux-gnu]
  38 llvm-config = "/path/to/llvm/llvm-7.0.1/bin/llvm-config"
  39 ```
  40
  41 If you are attempting to use a system LLVM, we have observed the following paths
  42 before, though they may be different from your system:
  43
  44 - `/usr/bin/llvm-config-8`
  45 - `/usr/lib/llvm-8/bin/llvm-config`
  46
  47 Note that you need to have the LLVM `FileCheck` tool installed, which is used
  48 for codegen tests. This tool is normally built with LLVM, but if you use your
  49 own preinstalled LLVM, you will need to provide `FileCheck` in some other way.
  50 On Debian-based systems, you can install the `llvm-N-tools` package (where `N`
  51 is the LLVM version number, e.g. `llvm-8-tools`). Alternately, you can specify
  52 the path to `FileCheck` with the `llvm-filecheck` config item in `config.toml`
  53 or you can disable codegen test with the `codegen-tests` item in `config.toml`.
  54
  55 ## Creating a target specification
  56
  57 You should start with a target JSON file. You can see the specification
  58 for an existing target using `--print target-spec-json`:
  59
  60 ```
  61 rustc -Z unstable-options --target=wasm32-unknown-unknown --print target-spec-json
  62 ```
  63
  64 Save that JSON to a file and modify it as appropriate for your target.
  65
  66 ### Adding a target specification
  67
  68 Once you have filled out a JSON specification and been able to compile
  69 somewhat successfully, you can copy the specification into the
  70 compiler itself.
  71
  72 You will need to add a line to the big table inside of the
  73 `supported_targets` macro in the `rustc_target::spec` module. You
  74 will then add a corresponding file for your new target containing a
  75 `target` function.
  76
  77 Look for existing targets to use as examples
  78
  79 ## Patching crates
  80
  81 You may need to make changes to crates that the compiler depends on,
  82 such as [`libc`][] or [`cc`][]. If so, you can use Cargo's
  83 [`[patch]`][patch] ability. For example, if you want to use an
  84 unreleased version of `libc`, you can add it to the top-level
  85 `Cargo.toml` file:
  86
  87 ```diff
  88 diff --git a/Cargo.toml b/Cargo.toml
  89 index be15e50e2bc..4fb1248ba99 100644
  90 --- a/Cargo.toml
  91 +++ b/Cargo.toml
  92 @@ -66,10 +66,11 @@ cargo = { path = "src/tools/cargo" }
  93  [patch.crates-io]
  94  # Similar to Cargo above we want the RLS to use a vendored version of `rustfmt`
  95  # that we're shipping as well (to ensure that the rustfmt in RLS and the
  96  # `rustfmt` executable are the same exact version).
  97  rustfmt-nightly = { path = "src/tools/rustfmt" }
  98 +libc = { git = "https://github.com/rust-lang/libc", rev = "0bf7ce340699dcbacabdf5f16a242d2219a49ee0" }
  99
 100  # See comments in `src/tools/rustc-workspace-hack/README.md` for what's going on
 101  # here
 102  rustc-workspace-hack = { path = 'src/tools/rustc-workspace-hack' }
 103 ```
 104
 105 After this, run `cargo update -p libc` to update the lockfiles.
 106
 107 [`libc`]: https://crates.io/crates/libc
 108 [`cc`]: https://crates.io/crates/cc
 109 [patch]: https://doc.rust-lang.org/stable/cargo/reference/overriding-dependencies.html#the-patch-section
 110
 111 ## Cross-compiling
 112
 113 Once you have a target specification in JSON and in the code, you can
 114 cross-compile `rustc`:
 115
 116 ```
 117 DESTDIR=/path/to/install/in \
 118 ./x.py install -i --stage 1 --host aarch64-apple-darwin.json --target aarch64-apple-darwin \
 119 compiler/rustc library/std
 120 ```
 121
 122 If your target specification is already available in the bootstrap
 123 compiler, you can use it instead of the JSON file for both arguments.
 124
 125 ## Promoting a target from tier 2 (target) to tier 2 (host)
 126
 127 There are two levels of tier 2 targets:
 128 a) Targets that are only cross-compiled (`rustup target add`)
 129 b) Targets that have a native toolchain (`rustup toolchain install`)
 130
 131 For an example of promoting a target from cross-compiled to native,
 132 see [#75914](https://github.com/rust-lang/rust/pull/75914).