Document cross-compiling Wasmtime (bytecodealliance#1721)

Closes bytecodealliance#1720

Author: alexcrichton

docs/contributing-building.md

@@ -52,6 +52,19 @@ The built executable will be located at `target/release/wasmtime`.
 You can also build and run a local `wasmtime` CLI by replacing `cargo build`
 with `cargo run`.
 
+## Building the Wasmtime C API
+
+To build the C API of Wasmtime you can run:
+
+```shell
+cargo build --release --manifest-path crates/c-api/Cargo.toml
+```
+
+This will place the shared library inside of `target/release`. On Linux it will
+be called `libwasmtime.{a,so}`, on macOS it will be called
+`libwasmtime.{a,dylib}`, and on Windows it will be called
+`wasmtime.{lib,dll,dll.lib}`.
+
 ## Building Other Wasmtime Crates
 
 You can build any of the Wasmtime crates by appending `-p wasmtime-whatever` to
@@ -69,3 +82,63 @@ there, without needing to supply the `-p` flag:
 cd crates/jit/
 cargo build
 ```
+
+## Cross Compiling Wasmtime
+
+By default `cargo build` will build Wasmtime for the platform you're running the
+build on. You might, however, want to build Wasmtime for a different platform!
+Let's say for example that you want to build Wasmtime for
+`aarch64-unknown-linux-gnu`. First you'll want to acquire the Rust standard
+library for this target:
+
+```shell
+rustup target add aarch64-unknown-linux-gnu
+```
+
+Next you need to install a native C toolchain which has a C compiler, runtime
+libraries, and linker for the desired target. This is unfortunately not very
+easy to acquire on most platforms:
+
+* On Windows you can install build tools for AArch64 Windows, but targeting
+  platforms like Linux or macOS is not easy. While toolchains exist for
+  targeting non-Windows platforms you'll have to hunt yourself to find the right
+  one.
+
+* On macOS you can install, through Xcode, toolchains for iOS but the main
+  `x86_64-apple-darwin` is really the only easy target to install. You'll need
+  to hunt for toolchains if you want to compile for Linux or Windows.
+
+* On Linux you can relatively easily compile for other Linux architectures most
+  of the time. For example on Debian-based distributions you can install the
+  `gcc-aarch64-linux-gnu` package which should come with the C compiler, runtime
+  libraries, and linker all in one (assuming you don't explicitly request
+  disabling recommended packages). Other Linux distributions may have
+  differently named toolchains. Compiling for macOS from Linux will require
+  finding your own toolchain. Compiling for Windows MSVC will require finding
+  your own toolchain, but compiling for MinGW can work easily enough if you
+  install the MinGW toolchain via your package manager.
+
+For now we'll assume you're on Linux compiling for a different Linux
+architecture.  Once you've got the native toolchain, you'll want to find the C
+compiler that came with it. On Debian, for example, this is called
+`aarch64-linux-gnu-gcc`. Next up you'll need to configure two environment
+variables to configure the Rust build:
+
+```shell
+export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc
+export CC_aarch64_unknown_linux_gnu=aarch64-linux-gnu-gcc
+```
+
+The first environment variable tells Cargo to tell rustc what the correct linker
+for your target is. The second configures the [`cc` Rust
+crate](https://crates.io/crates/cc) for C code compiled as part of the build.
+
+Finally you can execute.
+
+```shell
+cargo build --target aarch64-unknown-linux-gnu --release
+```
+
+The built executable will be located at
+`target/aarch64-unknown-linux-gnu/release/wasmtime`. Note that you can
+cross-compile the C API in the same manner as the CLI too.