compiler/rustc_target/src/spec/wasm32_wasi.rs

   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::{crt_objects, wasm_base, Cc, LinkerFlavor, Target};
  76
  77 pub fn target() -> Target {
  78     let mut options = wasm_base::options();
  79
  80     options.os = "wasi".into();
  81     options.add_pre_link_args(LinkerFlavor::WasmLld(Cc::Yes), &["--target=wasm32-wasi"]);
  82
  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();
  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
  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
  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
 103     Target {
 104         llvm_target: "wasm32-wasi".into(),
 105         pointer_width: 32,
 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(),
 108         options,
 109     }
 110 }