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.
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.
10 //! You can see more about the proposal at <https://wasi.dev>.
12 //! The Rust target definition here is interesting in a few ways. We want to
13 //! serve two use cases here with this target:
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
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`.
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
30 //! ## No interop with C required
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
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).
45 //! ## Interop with C required
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.
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
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
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.
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`
68 //! ## Remember, this is all in flux
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!
75 use super::crt_objects::{self, LinkSelfContainedDefault};
76 use super::{wasm_base, Cc, LinkerFlavor, Target};
78 pub fn target() -> Target {
79 let mut options = wasm_base::options();
81 options.os = "wasi".into();
82 options.add_pre_link_args(LinkerFlavor::WasmLld(Cc::Yes), &["--target=wasm32-wasi"]);
84 options.pre_link_objects_self_contained = crt_objects::pre_wasi_self_contained();
85 options.post_link_objects_self_contained = crt_objects::post_wasi_self_contained();
87 // FIXME: Figure out cases in which WASM needs to link with a native toolchain.
88 options.link_self_contained = LinkSelfContainedDefault::True;
90 // Right now this is a bit of a workaround but we're currently saying that
91 // the target by default has a static crt which we're taking as a signal
92 // for "use the bundled crt". If that's turned off then the system's crt
93 // will be used, but this means that default usage of this target doesn't
94 // need an external compiler but it's still interoperable with an external
95 // compiler if configured correctly.
96 options.crt_static_default = true;
97 options.crt_static_respected = true;
99 // Allow `+crt-static` to create a "cdylib" output which is just a wasm file
100 // without a main function.
101 options.crt_static_allows_dylibs = true;
103 // WASI's `sys::args::init` function ignores its arguments; instead,
104 // `args::args()` makes the WASI API calls itself.
105 options.main_needs_argc_argv = false;
108 llvm_target: "wasm32-wasi".into(),
110 data_layout: "e-m:e-p:32:32-p10:8:8-p20:8:8-i64:64-n32:64-S128-ni:1:10:20".into(),
111 arch: "wasm32".into(),