Update linking docs

[mwilliamson]

I've just finished updating a toy compiler to output object files instead of using the text format, so I thought it'd be good to include things that weren't clear to me from reading through the linking docs.

There are some details that I think would still be useful to include somewhere, although I'm not sure what the most appropriate place would be, nor am I sure whether there are alternative methods for the below. My impression, mostly from writing some C code and inspecting the resulting object file, is:

• rather than defining memory in the object file, memory should be imported from env.__linear_memory
• rather than defining a function table, one should be imported from env.__indirect_function_table
• on recent (>= 12) versions of LLVM, if __wasm_call_ctors is not called, then each exported function is wrapped in a function that first calls __wasm_call_ctors before calling the original function

I should also add that the fact that I was able to get things working within roughly a weekend, despite not being well versed in this sort of stuff, is a positive sign to some combination of an understandable design and good docs. So, thanks for putting this together in the first place!

[mwilliamson]

There are some details that I think would still be useful to include somewhere, although I'm not sure what the most appropriate place would be, nor am I sure whether there are alternative methods for the below. My impression, mostly from writing some C code and inspecting the resulting object file, is:

* rather than defining memory in the object file, memory should be imported from `env.__linear_memory`

* rather than defining a function table, one should be imported from `env.__indirect_function_table`

* on recent (>= 12) versions of LLVM, if `__wasm_call_ctors` is not called, then each exported function is wrapped in a function that first calls `__wasm_call_ctors` before calling the original function

Did you have any thoughts on whether the linking docs are the right place to put these sorts of details?

[sbc100]

There are some details that I think would still be useful to include somewhere, although I'm not sure what the most appropriate place would be, nor am I sure whether there are alternative methods for the below. My impression, mostly from writing some C code and inspecting the resulting object file, is:

* rather than defining memory in the object file, memory should be imported from `env.__linear_memory`

* rather than defining a function table, one should be imported from `env.__indirect_function_table`

* on recent (>= 12) versions of LLVM, if `__wasm_call_ctors` is not called, then each exported function is wrapped in a function that first calls `__wasm_call_ctors` before calling the original function

Did you have any thoughts on whether the linking docs are the right place to put these sorts of details?

I think that kind of stuff is more about the runtime ABI (i.e. that ABI used after everything is linked).

That probably belongs more in either https://github.com/WebAssembly/tool-conventions/blob/master/BasicCABI.md or https://github.com/WebAssembly/WASI/blob/main/design/application-abi.md

[sunfishcode]

@sbc100 I was under the impression that env.__linear_memory etc. were .o file things here, since neither the BasicCABI nor WASI intend to require modules to import their linear memory.

[sbc100]

Sorry yes, if you are talking about object files then we can/should mention __linear_memory and __indirect_function_table although I'm not actually sure how much the linker cares about those existing in object file. I think they are mostly there to make the object files validate. So I'd need to check how much we specify there.. at least for memory I'm pretty sure the linker doesn't care if the memory is imported or exports or what its name is.