exec: add example for VM usage

[sbinet]

Updates #60.

---

This change is 

[andreimatei]

Thank you very much for writing this. Should definitely help me get started!
I only have a few requests for more words.

I'd suggest linking to this example from the repo's README.
For this being sufficient for newcomers on its own, it'd be great if it also included the passing of a string or []byte to wasm.

And since we're talking, do you have any experience with producing wasm from C++ or any other language? Should I expect wagon to work with modules produced by emscripten, for example? I'm particularly curious how emscripten handles references to the C/C++ standard library. I read that it uses musl and that if you don't ask it to optimize for space it will produce humongous modules.

---

Review status: 0 of 5 files reviewed, 8 unresolved discussions (waiting on @sbinet)

---

exec/vm_example_test.go, line 24 at r1 (raw file):

	}

	m, err := wasm.ReadModule(bytes.NewReader(raw), func(name string) (*wasm.Module, error) {

it'd be good, at least for me, to explain a bit how linking works in the wasm world, and how that affects wagon. In this test we're manually handling the loading of one module (add-ex-main.wast) and then providing it with a resolver that handles both the imported "add" and "go". Would it also be possible for add-ex.wast and add-ex-main.wast to be linked together by a tool from the toolchain?
Consider adding some words about this if there's anything to be said.

---

exec/vm_example_test.go, line 37 at r1 (raw file):

			}
			return add, nil
		case "go":

call out the awesome fact that "go" is not a module we're loading, but one we're synthesizing.

---

exec/vm_example_test.go, line 46 at r1 (raw file):

				Entries: []wasm.FunctionSig{
					{
						Form:       0,

pls comment this Form field

---

exec/vm_example_test.go, line 55 at r1 (raw file):

					Sig:  &m.Types.Entries[0],
					Host: reflect.ValueOf(print),
					Body: &wasm.FunctionBody{},

what's up with this ptr to an empty struct? If it is needed, consider adding a comment (there are none at the Function definition site); one would expect it to be either-or with Host.

---

exec/vm_example_test.go, line 75 at r1 (raw file):

	vm, err := exec.NewVM(m)
	if err != nil {
		log.Fatalf("could not create wagon vm: %v", err)

nit: here and elsewhere, since err is known no be != nil, using %s would be clearer.

---

exec/vm_example_test.go, line 106 at r1 (raw file):

}

func compileWast2Wasm(fname string) ([]byte, error) {

I'm not sure I understand the need for this function, and calling it "compile" sure is misleading :)
I'd say make the test read the wasm files directly and put the assembler instructions in the main test func. You can also link to the issue calling out for an assembler to be implemented.

---

exec/testdata/add-ex.wast, line 2 at r1 (raw file):

(module
  (type (;0;) (func (param i32 i32) (result i32)))

unless the ;0;bit is understood by everybody, it would perhaps be worth an explanation

---

exec/testdata/add-ex.wast, line 3 at r1 (raw file):

(module
  (type (;0;) (func (param i32 i32) (result i32)))
  (func (;0;) (type 0) (param i32 i32) (result i32)

for my edification - what does type 0 mean here? I realize it's referring to the type we defined above, but it seems redundant with the rest of the function signature...

---

Comments from Reviewable

[andreimatei]

To answer my last question, I've had good luck compiling simple C functions with emcc -Os.

---

Review status: 0 of 5 files reviewed, 8 unresolved discussions (waiting on @sbinet)

---

Comments from Reviewable

[andreimatei]

Review status: 0 of 5 files reviewed, 9 unresolved discussions (waiting on @sbinet)

---

exec/vm_example_test.go, line 71 at r1 (raw file):

		}
		return nil, fmt.Errorf("module %q unknown", name)
	})

you forgot to check for the returned err here

---

Comments from Reviewable

[vmesel]

That is a pretty nice PR that solves a problem that I'm passing on.

[sbinet]

Review status: 0 of 5 files reviewed, 8 unresolved discussions (waiting on @andreimatei and @sbinet)

---

exec/vm_example_test.go, line 24 at r1 (raw file):

Previously, andreimatei (Andrei Matei) wrote…

it'd be good, at least for me, to explain a bit how linking works in the wasm world, and how that affects wagon. In this test we're manually handling the loading of one module (add-ex-main.wast) and then providing it with a resolver that handles both the imported "add" and "go". Would it also be possible for add-ex.wast and add-ex-main.wast to be linked together by a tool from the toolchain?
Consider adding some words about this if there's anything to be said.

Done. (I think)

---

exec/vm_example_test.go, line 37 at r1 (raw file):

Previously, andreimatei (Andrei Matei) wrote…

call out the awesome fact that "go" is not a module we're loading, but one we're synthesizing.

Done.

---

exec/vm_example_test.go, line 46 at r1 (raw file):

Previously, andreimatei (Andrei Matei) wrote…

pls comment this Form field

Done.

---

exec/vm_example_test.go, line 55 at r1 (raw file):

Previously, andreimatei (Andrei Matei) wrote…

what's up with this ptr to an empty struct? If it is needed, consider adding a comment (there are none at the Function definition site); one would expect it to be either-or with Host.

Done.

---

exec/vm_example_test.go, line 71 at r1 (raw file):

Previously, andreimatei (Andrei Matei) wrote…

you forgot to check for the returned err here

Done. (good catch!)

---

exec/vm_example_test.go, line 75 at r1 (raw file):

Previously, andreimatei (Andrei Matei) wrote…

nit: here and elsewhere, since err is known no be != nil, using %s would be clearer.

I usually prefer to use %v for all kind of error values and only use %s for real strings.

---

exec/vm_example_test.go, line 106 at r1 (raw file):

Previously, andreimatei (Andrei Matei) wrote…

I'm not sure I understand the need for this function, and calling it "compile" sure is misleading :)
I'd say make the test read the wasm files directly and put the assembler instructions in the main test func. You can also link to the issue calling out for an assembler to be implemented.

I am leaning towards just adding a snarky comment about the lack of WAST->WASM compilation support (linking towards the issue) and leave it at that.
it's really to show the expected workflow (but pushing the missing features under the rug so everything looks kind of clean.)
it's also to show what's supposed to be inside the .wasm files, and looking at a .wast file is easier for humans :)

---

exec/testdata/add-ex.wast, line 2 at r1 (raw file):

Previously, andreimatei (Andrei Matei) wrote…

unless the ;0;bit is understood by everybody, it would perhaps be worth an explanation

Done. (I have linked to the specs. (; ;) is just an inline comment like /* */ is in C/C++.)
here, (; 0 ;) is just to help the human reader notice the index of that type.

---

exec/testdata/add-ex.wast, line 3 at r1 (raw file):

Previously, andreimatei (Andrei Matei) wrote…

for my edification - what does type 0 mean here? I realize it's referring to the type we defined above, but it seems redundant with the rest of the function signature...

yeah... redundant but this allows to have a linear definition for the module.

---

Comments from Reviewable

[sbinet]

Reviewed 2 of 5 files at r1, 3 of 3 files at r2.
Review status: all files reviewed, 8 unresolved discussions (waiting on @andreimatei)

---

Comments from Reviewable