From 6832753bd6e2420492bc1460db31865a6b12da68 Mon Sep 17 00:00:00 2001 From: JF Bastien Date: Sat, 19 Sep 2015 12:26:44 -0700 Subject: Official text format, or lack thereof The official documents haven't really clarified what we're doing with the text format, and that leads to confusion: http://stackoverflow.com/questions/32666337/will-web-assembly-wasm-have-its-own-syntax/ This edit mentions all the current text formats. --- TextFormat.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) (limited to 'TextFormat.md') diff --git a/TextFormat.md b/TextFormat.md index 316b065..8254590 100644 --- a/TextFormat.md +++ b/TextFormat.md @@ -34,7 +34,35 @@ represented as hexadecimal floating-point as specified by the C99 standard, whic IEEE-754-2008 section 5.12.3 also specifies. The textual format may be improved to also support more human-readable representations, but never at the cost of accurate representation. -## Debug symbol integration +# Official Text Format + +WebAssembly currently doesn't have a final, official, text format. As detailed above the +main purpose of the text format will be for human consumption, humans feedback on readability +will therefore factor into standardizing a text format. + +There are, however, prototype syntaxes which are used to bring up WebAssembly: it's easier +to develop using a text format than it is with a binary format, even if the ultimate +WebAssembly format will be binary. Most of these prototypes use [s-expressions][] because they +can easily represent expression trees and [ASTs](ASTSemantics.md) (as opposed to CFGs). + + [s-expressions]: https://en.wikipedia.org/wiki/S-expression + +* [Prototype specification][] consumes an s-expression syntax. +* [WAVM backend][] consumes compatible s-expressions. +* [sexpr-wasm prototype][] consumes compatible s-expressions, and works closely with the [V8 prototype][]. +* [LLVM backend][] (the `CHECK:` parts of these tests) emits compatible s-expressions. +* [ilwasm][] emits compatible s-expressions. +* [wassembler][] consumes a different syntax, and works closely with the [V8 prototype][]. + + [prototype specification]: https://github.com/WebAssembly/spec/tree/master/ml-proto/test + [LLVM backend]: https://github.com/llvm-mirror/llvm/tree/master/test/CodeGen/WebAssembly + [WAVM backend]: https://github.com/AndrewScheidecker/WAVM/tree/master/Test + [wassembler]: https://github.com/ncbray/wassembler/tree/master/demos + [V8 prototype]: https://github.com/WebAssembly/v8-native-prototype + [ilwasm]: https://github.com/WebAssembly/ilwasm + [sexpr-wasm prototype]: https://github.com/WebAssembly/sexpr-wasm-prototype + +# Debug symbol integration The binary format inherently strips names from functions, locals, globals, etc, reducing each of these to dense indices. Without help, the text format must -- cgit v1.2.3 From c8dff1d01fb3476e090e9ce18b8b27ba2fab38c6 Mon Sep 17 00:00:00 2001 From: JF Bastien Date: Sat, 19 Sep 2015 16:15:52 -0700 Subject: Address human feedback --- TextFormat.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'TextFormat.md') diff --git a/TextFormat.md b/TextFormat.md index 8254590..c6530e9 100644 --- a/TextFormat.md +++ b/TextFormat.md @@ -37,8 +37,8 @@ support more human-readable representations, but never at the cost of accurate r # Official Text Format WebAssembly currently doesn't have a final, official, text format. As detailed above the -main purpose of the text format will be for human consumption, humans feedback on readability -will therefore factor into standardizing a text format. +main purpose of the text format will be for human consumption, feedback from humans on +readability will therefore factor into standardizing a text format. There are, however, prototype syntaxes which are used to bring up WebAssembly: it's easier to develop using a text format than it is with a binary format, even if the ultimate -- cgit v1.2.3 From b8b39799663ab2ad91847022248a6650c42b8c4a Mon Sep 17 00:00:00 2001 From: JF Bastien Date: Sun, 20 Sep 2015 14:54:27 -0700 Subject: Avoid bikeshed --- TextFormat.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'TextFormat.md') diff --git a/TextFormat.md b/TextFormat.md index c6530e9..86a2641 100644 --- a/TextFormat.md +++ b/TextFormat.md @@ -43,7 +43,8 @@ readability will therefore factor into standardizing a text format. There are, however, prototype syntaxes which are used to bring up WebAssembly: it's easier to develop using a text format than it is with a binary format, even if the ultimate WebAssembly format will be binary. Most of these prototypes use [s-expressions][] because they -can easily represent expression trees and [ASTs](ASTSemantics.md) (as opposed to CFGs). +can easily represent expression trees and [ASTs](ASTSemantics.md) (as opposed to CFGs) +and don't have much of a syntax to speak of (avoiding syntax bikeshed discussions). [s-expressions]: https://en.wikipedia.org/wiki/S-expression -- cgit v1.2.3 From f1de8db290813d7e3f1bc000f85388d563c0dab0 Mon Sep 17 00:00:00 2001 From: JF Bastien Date: Mon, 21 Sep 2015 15:49:54 -0700 Subject: Some prototypes --- TextFormat.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'TextFormat.md') diff --git a/TextFormat.md b/TextFormat.md index 86a2641..f16db3b 100644 --- a/TextFormat.md +++ b/TextFormat.md @@ -48,6 +48,8 @@ and don't have much of a syntax to speak of (avoiding syntax bikeshed discussion [s-expressions]: https://en.wikipedia.org/wiki/S-expression +Here are some of these prototypes. Keep in mind that these *aren't* official: + * [Prototype specification][] consumes an s-expression syntax. * [WAVM backend][] consumes compatible s-expressions. * [sexpr-wasm prototype][] consumes compatible s-expressions, and works closely with the [V8 prototype][]. -- cgit v1.2.3 From 4d7e98f257b0af434a31ed20199e743e7ea96e0c Mon Sep 17 00:00:00 2001 From: JF Bastien Date: Mon, 21 Sep 2015 16:39:08 -0700 Subject: Official may be different --- TextFormat.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'TextFormat.md') diff --git a/TextFormat.md b/TextFormat.md index f16db3b..3132c6a 100644 --- a/TextFormat.md +++ b/TextFormat.md @@ -48,7 +48,8 @@ and don't have much of a syntax to speak of (avoiding syntax bikeshed discussion [s-expressions]: https://en.wikipedia.org/wiki/S-expression -Here are some of these prototypes. Keep in mind that these *aren't* official: +Here are some of these prototypes. Keep in mind that these *aren't* official, and the final +official format may look entirely different: * [Prototype specification][] consumes an s-expression syntax. * [WAVM backend][] consumes compatible s-expressions. -- cgit v1.2.3