]>
Commit | Line | Data |
---|---|---|
6a06907d XL |
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 .. | |
94222f64 | 23 | git add llvm-project |
6a06907d XL |
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 | |
94222f64 XL |
30 | able to configure Rust to treat your build as the system LLVM to avoid |
31 | redundant builds. | |
6a06907d XL |
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 | ||
94222f64 | 77 | Look for existing targets to use as examples. |
6a06907d XL |
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: | |
94222f64 XL |
128 | a) Targets that are only cross-compiled (`rustup target add`) |
129 | b) Targets that [have a native toolchain][tier2-native] (`rustup toolchain install`) | |
130 | ||
131 | [tier2-native]: https://doc.rust-lang.org/nightly/rustc/target-tier-policy.html#tier-2-with-host-tools | |
6a06907d XL |
132 | |
133 | For an example of promoting a target from cross-compiled to native, | |
134 | see [#75914](https://github.com/rust-lang/rust/pull/75914). |