From 5bf929243cd8f2ce0388bccc4009ace8e01d18b2 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Sat, 2 May 2015 13:47:03 -0700 Subject: clarify the purpose of the binary format, and its equivalence to the text format --- V1.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/V1.md b/V1.md index 1b65612..1013cf4 100644 --- a/V1.md +++ b/V1.md @@ -14,7 +14,7 @@ precise descriptions of: * At the top level, a module is ELF-like: a squence of sections which declare their type and byte-length. * Sections with unknown types would be skipped without error. * Standardized section types: - * module import section (see [Module imports](V1.md#module-imports) below) + * module import section (see [Module imports](V1.md#module-imports) below) * globals section (constants, signatures, variables) * code section (see [Code section](V1.md#code-section) below) * heap initialization section (see [Heap](V1.md#heap) below) @@ -40,7 +40,10 @@ precise descriptions of: * See the [AST Semantics](AstSemantics.md) for descriptions of individual AST nodes. ## Binary format -* This is the format natively decoded by the browser. +* The sole purpose of this format is efficiency: reducing download size and making decoding + faster, thus enabling even very large codebases to have quick startup times. + * Towards that goal, the binary format will be natively decoded by the browser. +* The binary format has an equivalent and isomorphic [text format](V1.md#text-format). * Do not try to compete with a generic compression algorithm by trying to suck out every last bit; assume a generic compression algorithm is applied on top of the binary encoding. * "Given that text is so compressible and it is well known that it is hard to beat gzipped source, @@ -58,10 +61,12 @@ precise descriptions of: ## Text format * The purpose of this format is to support: - * View Source on a WebAssembly module. + * View Source on a WebAssembly module, thus fitting into the Web (where every source can + be viewed) in a natural way. * Presentation in browser devtools when source maps aren't present (which is necessarily the case with v.1). * Writing WebAssembly code directly for reasons including pedagogical, experimental, debugging, or optimization. +* The text format is equivalent and isomorphic to the [binary format](V1.md#binary-format). * Given that the code representation is actually an AST, the syntax would contain nested statements and expressions (instead of the linear list of instructions most assembly languages have). * There is no requirement to use JS syntax; this format is not intended to be evaluated or translated -- cgit v1.2.3