]>
Commit | Line | Data |
---|---|---|
48663c56 | 1 | //! The `wasm32-wasi` target is a new and still (as of April 2019) an |
532ac7d7 XL |
2 | //! experimental target. The definition in this file is likely to be tweaked |
3 | //! over time and shouldn't be relied on too much. | |
4 | //! | |
5 | //! The `wasi` target is a proposal to define a standardized set of syscalls | |
6 | //! that WebAssembly files can interoperate with. This set of syscalls is | |
7 | //! intended to empower WebAssembly binaries with native capabilities such as | |
8 | //! filesystem access, network access, etc. | |
9 | //! | |
29967ef6 | 10 | //! You can see more about the proposal at <https://wasi.dev>. |
532ac7d7 XL |
11 | //! |
12 | //! The Rust target definition here is interesting in a few ways. We want to | |
13 | //! serve two use cases here with this target: | |
14 | //! | |
15 | //! * First, we want Rust usage of the target to be as hassle-free as possible, | |
48663c56 XL |
16 | //! ideally avoiding the need to configure and install a local wasm32-wasi |
17 | //! toolchain. | |
532ac7d7 XL |
18 | //! |
19 | //! * Second, one of the primary use cases of LLVM's new wasm backend and the | |
20 | //! wasm support in LLD is that any compiled language can interoperate with | |
48663c56 XL |
21 | //! any other. To that the `wasm32-wasi` target is the first with a viable C |
22 | //! standard library and sysroot common definition, so we want Rust and C/C++ | |
23 | //! code to interoperate when compiled to `wasm32-unknown-unknown`. | |
532ac7d7 XL |
24 | //! |
25 | //! You'll note, however, that the two goals above are somewhat at odds with one | |
26 | //! another. To attempt to solve both use cases in one go we define a target | |
27 | //! that (ab)uses the `crt-static` target feature to indicate which one you're | |
28 | //! in. | |
29 | //! | |
30 | //! ## No interop with C required | |
31 | //! | |
32 | //! By default the `crt-static` target feature is enabled, and when enabled | |
1b1a35ee | 33 | //! this means that the bundled version of `libc.a` found in `liblibc.rlib` |
532ac7d7 XL |
34 | //! is used. This isn't intended really for interoperation with a C because it |
35 | //! may be the case that Rust's bundled C library is incompatible with a | |
36 | //! foreign-compiled C library. In this use case, though, we use `rust-lld` and | |
37 | //! some copied crt startup object files to ensure that you can download the | |
38 | //! wasi target for Rust and you're off to the races, no further configuration | |
39 | //! necessary. | |
40 | //! | |
41 | //! All in all, by default, no external dependencies are required. You can | |
48663c56 XL |
42 | //! compile `wasm32-wasi` binaries straight out of the box. You can't, however, |
43 | //! reliably interoperate with C code in this mode (yet). | |
532ac7d7 XL |
44 | //! |
45 | //! ## Interop with C required | |
46 | //! | |
47 | //! For the second goal we repurpose the `target-feature` flag, meaning that | |
48 | //! you'll need to do a few things to have C/Rust code interoperate. | |
49 | //! | |
50 | //! 1. All Rust code needs to be compiled with `-C target-feature=-crt-static`, | |
51 | //! indicating that the bundled C standard library in the Rust sysroot will | |
52 | //! not be used. | |
53 | //! | |
54 | //! 2. If you're using rustc to build a linked artifact then you'll need to | |
55 | //! specify `-C linker` to a `clang` binary that supports | |
48663c56 XL |
56 | //! `wasm32-wasi` and is configured with the `wasm32-wasi` sysroot. This |
57 | //! will cause Rust code to be linked against the libc.a that the specified | |
58 | //! `clang` provides. | |
532ac7d7 XL |
59 | //! |
60 | //! 3. If you're building a staticlib and integrating Rust code elsewhere, then | |
61 | //! compiling with `-C target-feature=-crt-static` is all you need to do. | |
62 | //! | |
63 | //! You can configure the linker via Cargo using the | |
48663c56 XL |
64 | //! `CARGO_TARGET_WASM32_WASI_LINKER` env var. Be sure to also set |
65 | //! `CC_wasm32-wasi` if any crates in the dependency graph are using the `cc` | |
66 | //! crate. | |
532ac7d7 XL |
67 | //! |
68 | //! ## Remember, this is all in flux | |
69 | //! | |
70 | //! The wasi target is **very** new in its specification. It's likely going to | |
71 | //! be a long effort to get it standardized and stable. We'll be following it as | |
72 | //! best we can with this target. Don't start relying on too much here unless | |
73 | //! you know what you're getting in to! | |
74 | ||
2b03887a | 75 | use super::{crt_objects, wasm_base, Cc, LinkerFlavor, Target}; |
532ac7d7 | 76 | |
29967ef6 | 77 | pub fn target() -> Target { |
cdc7bbd5 | 78 | let mut options = wasm_base::options(); |
532ac7d7 | 79 | |
5e7ed085 | 80 | options.os = "wasi".into(); |
2b03887a | 81 | options.add_pre_link_args(LinkerFlavor::WasmLld(Cc::Yes), &["--target=wasm32-wasi"]); |
532ac7d7 | 82 | |
f2b60f7d FG |
83 | options.pre_link_objects_self_contained = crt_objects::pre_wasi_self_contained(); |
84 | options.post_link_objects_self_contained = crt_objects::post_wasi_self_contained(); | |
532ac7d7 XL |
85 | |
86 | // Right now this is a bit of a workaround but we're currently saying that | |
87 | // the target by default has a static crt which we're taking as a signal | |
88 | // for "use the bundled crt". If that's turned off then the system's crt | |
89 | // will be used, but this means that default usage of this target doesn't | |
90 | // need an external compiler but it's still interoperable with an external | |
91 | // compiler if configured correctly. | |
92 | options.crt_static_default = true; | |
93 | options.crt_static_respected = true; | |
94 | ||
e1599b0c XL |
95 | // Allow `+crt-static` to create a "cdylib" output which is just a wasm file |
96 | // without a main function. | |
97 | options.crt_static_allows_dylibs = true; | |
98 | ||
e74abb32 XL |
99 | // WASI's `sys::args::init` function ignores its arguments; instead, |
100 | // `args::args()` makes the WASI API calls itself. | |
101 | options.main_needs_argc_argv = false; | |
102 | ||
29967ef6 | 103 | Target { |
5e7ed085 | 104 | llvm_target: "wasm32-wasi".into(), |
29967ef6 | 105 | pointer_width: 32, |
5e7ed085 FG |
106 | data_layout: "e-m:e-p:32:32-p10:8:8-p20:8:8-i64:64-n32:64-S128-ni:1:10:20".into(), |
107 | arch: "wasm32".into(), | |
532ac7d7 | 108 | options, |
29967ef6 | 109 | } |
532ac7d7 | 110 | } |