src/librustc_target/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 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::wasm32_base;
  76 use super::{LinkerFlavor, LldFlavor, Target};
  77
  78 pub fn target() -> Result<Target, String> {
  79     let mut options = wasm32_base::options();
  80
  81     options
  82         .pre_link_args
  83         .entry(LinkerFlavor::Gcc)
  84         .or_insert(Vec::new())
  85         .push("--target=wasm32-wasi".to_string());
  86
  87     // When generating an executable be sure to put the startup object at the
  88     // front so the main function is correctly hooked up.
  89     options.pre_link_objects_exe_crt.push("crt1.o".to_string());
  90
  91     // Right now this is a bit of a workaround but we're currently saying that
  92     // the target by default has a static crt which we're taking as a signal
  93     // for "use the bundled crt". If that's turned off then the system's crt
  94     // will be used, but this means that default usage of this target doesn't
  95     // need an external compiler but it's still interoperable with an external
  96     // compiler if configured correctly.
  97     options.crt_static_default = true;
  98     options.crt_static_respected = true;
  99
 100     // Allow `+crt-static` to create a "cdylib" output which is just a wasm file
 101     // without a main function.
 102     options.crt_static_allows_dylibs = true;
 103
 104     Ok(Target {
 105         llvm_target: "wasm32-wasi".to_string(),
 106         target_endian: "little".to_string(),
 107         target_pointer_width: "32".to_string(),
 108         target_c_int_width: "32".to_string(),
 109         target_os: "wasi".to_string(),
 110         target_env: String::new(),
 111         target_vendor: String::new(),
 112         data_layout: "e-m:e-p:32:32-i64:64-n32:64-S128".to_string(),
 113         arch: "wasm32".to_string(),
 114         linker_flavor: LinkerFlavor::Lld(LldFlavor::Wasm),
 115         options,
 116     })
 117 }