]>
Commit | Line | Data |
---|---|---|
1 | //! The `wasm32-wasi` target is a new and still (as of April 2019) an | |
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 | //! | |
10 | //! You can see more about the proposal at <https://wasi.dev>. | |
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, | |
16 | //! ideally avoiding the need to configure and install a local wasm32-wasi | |
17 | //! toolchain. | |
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 | |
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`. | |
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 | |
33 | //! this means that the bundled version of `libc.a` found in `liblibc.rlib` | |
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 | |
42 | //! compile `wasm32-wasi` binaries straight out of the box. You can't, however, | |
43 | //! reliably interoperate with C code in this mode (yet). | |
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 | |
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. | |
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 | |
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. | |
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 | ||
75 | use super::wasm_base; | |
76 | use super::{crt_objects, LinkerFlavor, LldFlavor, Target}; | |
77 | ||
78 | pub fn target() -> Target { | |
79 | let mut options = wasm_base::options(); | |
80 | ||
81 | options.os = "wasi".to_string(); | |
82 | options.linker_flavor = LinkerFlavor::Lld(LldFlavor::Wasm); | |
83 | options | |
84 | .pre_link_args | |
85 | .entry(LinkerFlavor::Gcc) | |
86 | .or_insert(Vec::new()) | |
87 | .push("--target=wasm32-wasi".to_string()); | |
88 | ||
89 | options.pre_link_objects_fallback = crt_objects::pre_wasi_fallback(); | |
90 | options.post_link_objects_fallback = crt_objects::post_wasi_fallback(); | |
91 | ||
92 | // Right now this is a bit of a workaround but we're currently saying that | |
93 | // the target by default has a static crt which we're taking as a signal | |
94 | // for "use the bundled crt". If that's turned off then the system's crt | |
95 | // will be used, but this means that default usage of this target doesn't | |
96 | // need an external compiler but it's still interoperable with an external | |
97 | // compiler if configured correctly. | |
98 | options.crt_static_default = true; | |
99 | options.crt_static_respected = true; | |
100 | ||
101 | // Allow `+crt-static` to create a "cdylib" output which is just a wasm file | |
102 | // without a main function. | |
103 | options.crt_static_allows_dylibs = true; | |
104 | ||
105 | // WASI's `sys::args::init` function ignores its arguments; instead, | |
106 | // `args::args()` makes the WASI API calls itself. | |
107 | options.main_needs_argc_argv = false; | |
108 | ||
109 | Target { | |
110 | llvm_target: "wasm32-wasi".to_string(), | |
111 | pointer_width: 32, | |
112 | data_layout: "e-m:e-p:32:32-p10:8:8-p20:8:8-i64:64-n32:64-S128-ni:1:10:20".to_string(), | |
113 | arch: "wasm32".to_string(), | |
114 | options, | |
115 | } | |
116 | } |