Improve README.md

[abrown]

This changes the front-page documentation to:

• use out-of-line links in more places
• mention the need for libclang_rt.builtins-wasm32.a when using
  standard Clang
• mention how to use a wasi-libc sysroot
• explain the experimental status of `wasm32-wasi-threads

[sbc100]

Nice!

[abrown]

Actually, is this true? I know this is true for building wasi-libc (see building from source) from having to do this myself but is it the case for the average program?

[sbc100]

I'm not sure exactly what you mean.

If your question is "can you get away without libclang_rt.builtins-wasm32.a" then the answer is no. All programs pretty much end up depending on this library and clang adds it to the link line by default.

Also, wasi-libc is not a program (its just a static library) so technically you don't need libclang_rt.builtins-wasm32.a to build wasi-libc.. but in order to use wasi-libc in any kind of normal program, that is when you would need the builtins library (i.e. when you actually want to link something).

Or did I misunderstand your question?

[abrown]

Ok, yeah, your response makes sense:

If your question is "can you get away without libclang_rt.builtins-wasm32.a" then the answer is no

That's what I thought but I started to confuse myself. So the language I'm using here does make sense: we need the builtins to just use vanilla Clang — it isn't as easy as "just point to a sysroot" as we previously had documented here.

Separately,

technically you don't need libclang_rt.builtins-wasm32.a to build wasi-libc

But the "we need the builtins" is documented in the wasi-libc instructions; maybe we should discuss that in WebAssembly/wasi-libc#425?