cranelift/docs/wasm-c.md

# C/C++

All the parts needed to support wasm are included in upstream clang, lld, and
compiler-rt, as of the LLVM 8.0 release. However, to use it, you'll need
to build WebAssembly-targeted versions of the library parts, and it can
be tricky to get all the CMake invocations lined up properly.

To make things easier, we provide
[prebuilt packages](https://github.com/WebAssembly/wasi-sdk/releases)
that provide builds of Clang and sysroot libraries.

WASI doesn't yet support `setjmp`/`longjmp` or C++ exceptions, as it is
waiting for [unwinding support in WebAssembly].

By default, the C/C++ toolchain orders linear memory to put the globals first,
the stack second, and start the heap after that. This reduces code size,
because references to globals can use small offsets. However, it also means
that stack overflow will often lead to corrupted globals. The
`-Wl,--stack-first` flag to clang instructs it to put the stack first, followed
by the globals and the heap, which may produce slightly larger code, but will
more reliably trap on stack overflow.

See the [wasm-ld documentation] for more information and additional flags. Note
flags related to dynamic linking, such `-shared` and `--export-dynamic` are
not yet stable and are expected to change behavior in the future.

[unwinding support in WebAssembly]: https://github.com/WebAssembly/exception-handling/
[wasm-ld documentation]: https://lld.llvm.org/WebAssembly.html
Add book documentation skeleton and auto-publish from CI (#435) This commit adds the skeleton of a new set of documentation for `wasmtime` in the existing `docs` directory. This documentation is organized and compiled with [mdbook] which the Rust project uses for most of its own documentation as well. At a previous meeting we brainstormed a rough skeleton of what the documentation in this book would look like, and I've transcribed that here for an example of how this is rendered and how it can be laid out. No actual documentation is written yet. This commit also additionally adds necessary support to auto-publish both this book documentation and API documentation every time a commit is pushed to the `master` branch. All HTML will be automatically pushed to the `gh-pages` branch so long as the CI passes, and this should get deployed to https://cranestation.github.io/wasmtime. I've done a few dry-runs and I think this'll all work, but we'll likely tweak a few things here and there after running this through CI to make sure everything looks just as we'd like. My hope though is that after this lands we can start actually filling out all the documentation and being able to review it as well. [mdbook]: https://crates.io/crates/mdbook 5 years ago			`# C/C++`
Spice up the project README, fill out more docs (#1010) * Spice up the project README, fill out more docs This is an attempt to spruce up wasmtime's README.md file as well as fill out more of the missing documentation in the `docs/` folder. There's still a long way to go but I hoped here to mostly move around existing information and add new information. As always happy to have feedback! * Tweak CLI wording * Remove no-longer relevant clause * Update sandboxing docs * Handle comments 5 years ago
			`All the parts needed to support wasm are included in upstream clang, lld, and`
			`compiler-rt, as of the LLVM 8.0 release. However, to use it, you'll need`
			`to build WebAssembly-targeted versions of the library parts, and it can`
			`be tricky to get all the CMake invocations lined up properly.`

			`To make things easier, we provide`
Miscelaneous docs updates and fixes. (#1249) Update references to things in CraneStation which have moved, WASI documentation which has moved to the WASI repo, and fix a few typos. 5 years ago			`[prebuilt packages](https://github.com/WebAssembly/wasi-sdk/releases)`
Spice up the project README, fill out more docs (#1010) * Spice up the project README, fill out more docs This is an attempt to spruce up wasmtime's README.md file as well as fill out more of the missing documentation in the `docs/` folder. There's still a long way to go but I hoped here to mostly move around existing information and add new information. As always happy to have feedback! * Tweak CLI wording * Remove no-longer relevant clause * Update sandboxing docs * Handle comments 5 years ago			`that provide builds of Clang and sysroot libraries.`

			WASI doesn't yet support `setjmp`/`longjmp` or C++ exceptions, as it is
			`waiting for [unwinding support in WebAssembly].`

Document the `-Wl,--stack-first` option to clang. As discussed in WebAssembly/wasi-libc#233, document the `-Wl,--stack-first` option to help users diagnose stack overflow errors. 4 years ago			`By default, the C/C++ toolchain orders linear memory to put the globals first,`
			`the stack second, and start the heap after that. This reduces code size,`
			`because references to globals can use small offsets. However, it also means`
			`that stack overflow will often lead to corrupted globals. The`
			`-Wl,--stack-first` flag to clang instructs it to put the stack first, followed
			`by the globals and the heap, which may produce slightly larger code, but will`
			`more reliably trap on stack overflow.`

Add a link to the wasm-ld documentation. 4 years ago			`See the [wasm-ld documentation] for more information and additional flags. Note`
			flags related to dynamic linking, such `-shared` and `--export-dynamic` are
			`not yet stable and are expected to change behavior in the future.`

Spice up the project README, fill out more docs (#1010) * Spice up the project README, fill out more docs This is an attempt to spruce up wasmtime's README.md file as well as fill out more of the missing documentation in the `docs/` folder. There's still a long way to go but I hoped here to mostly move around existing information and add new information. As always happy to have feedback! * Tweak CLI wording * Remove no-longer relevant clause * Update sandboxing docs * Handle comments 5 years ago			`[unwinding support in WebAssembly]: https://github.com/WebAssembly/exception-handling/`
Add a link to the wasm-ld documentation. 4 years ago			`[wasm-ld documentation]: https://lld.llvm.org/WebAssembly.html`