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 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::wasm32_base
;
76 use super::{crt_objects, LinkerFlavor, LldFlavor, Target}
;
78 pub fn target() -> Result
<Target
, String
> {
79 let mut options
= wasm32_base
::options();
83 .entry(LinkerFlavor
::Gcc
)
84 .or_insert(Vec
::new())
85 .push("--target=wasm32-wasi".to_string());
87 options
.pre_link_objects_fallback
= crt_objects
::pre_wasi_fallback();
88 options
.post_link_objects_fallback
= crt_objects
::post_wasi_fallback();
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".to_string(),
109 target_endian
: "little".to_string(),
110 target_pointer_width
: "32".to_string(),
111 target_c_int_width
: "32".to_string(),
112 target_os
: "wasi".to_string(),
113 target_env
: String
::new(),
114 target_vendor
: String
::new(),
115 data_layout
: "e-m:e-p:32:32-i64:64-n32:64-S128".to_string(),
116 arch
: "wasm32".to_string(),
117 linker_flavor
: LinkerFlavor
::Lld(LldFlavor
::Wasm
),