Modules¶

WebAssembly programs are organized into modules, which are the unit of deployment, loading, and compilation. A module collects definitions for types, functions, tables, memories, and globals. In addition, it can declare imports and exports and provide initialization logic in the form of data and element segments or a start function.

\[\begin{split}\begin{array}{lllll} \def\mathdef1558#1{{}}\mathdef1558{module} & \href{../syntax/modules.html#syntax-module}{\mathit{module}} &::=& \{ & \href{../syntax/modules.html#syntax-module}{\mathsf{types}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/types.html#syntax-functype}{\mathit{functype}}), \\&&&& \href{../syntax/modules.html#syntax-module}{\mathsf{funcs}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/modules.html#syntax-func}{\mathit{func}}), \\&&&& \href{../syntax/modules.html#syntax-module}{\mathsf{tables}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/modules.html#syntax-table}{\mathit{table}}), \\&&&& \href{../syntax/modules.html#syntax-module}{\mathsf{mems}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/modules.html#syntax-mem}{\mathit{mem}}), \\&&&& \href{../syntax/modules.html#syntax-module}{\mathsf{globals}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/modules.html#syntax-global}{\mathit{global}}), \\&&&& \href{../syntax/modules.html#syntax-module}{\mathsf{elem}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/modules.html#syntax-elem}{\mathit{elem}}), \\&&&& \href{../syntax/modules.html#syntax-module}{\mathsf{data}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/modules.html#syntax-data}{\mathit{data}}), \\&&&& \href{../syntax/modules.html#syntax-module}{\mathsf{start}}~\href{../syntax/modules.html#syntax-start}{\mathit{start}}^?, \\&&&& \href{../syntax/modules.html#syntax-module}{\mathsf{imports}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/modules.html#syntax-import}{\mathit{import}}), \\&&&& \href{../syntax/modules.html#syntax-module}{\mathsf{exports}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/modules.html#syntax-export}{\mathit{export}}) \quad\} \\ \end{array}\end{split}\]

Each of the vectors – and thus the entire module – may be empty.

Indices¶

Definitions are referenced with zero-based indices. Each class of definition has its own index space, as distinguished by the following classes.

\[\begin{split}\begin{array}{llll} \def\mathdef1558#1{{}}\mathdef1558{type index} & \href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}} &::=& \href{../syntax/values.html#syntax-int}{\mathit{u32}} \\ \def\mathdef1558#1{{}}\mathdef1558{function index} & \href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}} &::=& \href{../syntax/values.html#syntax-int}{\mathit{u32}} \\ \def\mathdef1558#1{{}}\mathdef1558{table index} & \href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}} &::=& \href{../syntax/values.html#syntax-int}{\mathit{u32}} \\ \def\mathdef1558#1{{}}\mathdef1558{memory index} & \href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}} &::=& \href{../syntax/values.html#syntax-int}{\mathit{u32}} \\ \def\mathdef1558#1{{}}\mathdef1558{global index} & \href{../syntax/modules.html#syntax-globalidx}{\mathit{globalidx}} &::=& \href{../syntax/values.html#syntax-int}{\mathit{u32}} \\ \def\mathdef1558#1{{}}\mathdef1558{local index} & \href{../syntax/modules.html#syntax-localidx}{\mathit{localidx}} &::=& \href{../syntax/values.html#syntax-int}{\mathit{u32}} \\ \def\mathdef1558#1{{}}\mathdef1558{label index} & \href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}} &::=& \href{../syntax/values.html#syntax-int}{\mathit{u32}} \\ \end{array}\end{split}\]

The index space for functions, tables, memories and globals includes respective imports declared in the same module. The indices of these imports precede the indices of other definitions in the same index space.

The index space for locals is only accessible inside a function and includes the parameters of that function, which precede the local variables.

Label indices reference structured control instructions inside an instruction sequence.

Conventions¶

The meta variable \(l\) ranges over label indices.
The meta variables \(x, y\) range over indices in any of the other index spaces.

Types¶

The \(\href{../syntax/modules.html#syntax-module}{\mathsf{types}}\) component of a module defines a vector of function types.

All function types used in a module must be defined in this component. They are referenced by type indices.

Note

Future versions of WebAssembly may add additional forms of type definitions.

Functions¶

The \(\href{../syntax/modules.html#syntax-module}{\mathsf{funcs}}\) component of a module defines a vector of functions with the following structure:

\[\begin{split}\begin{array}{llll} \def\mathdef1558#1{{}}\mathdef1558{function} & \href{../syntax/modules.html#syntax-func}{\mathit{func}} &::=& \{ \href{../syntax/modules.html#syntax-func}{\mathsf{type}}~\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}, \href{../syntax/modules.html#syntax-func}{\mathsf{locals}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/types.html#syntax-valtype}{\mathit{valtype}}), \href{../syntax/modules.html#syntax-func}{\mathsf{body}}~\href{../syntax/instructions.html#syntax-expr}{\mathit{expr}} \} \\ \end{array}\end{split}\]

The \(\href{../syntax/modules.html#syntax-func}{\mathsf{type}}\) of a function declares its signature by reference to a type defined in the module. The parameters of the function are referenced through 0-based local indices in the function’s body; they are mutable.

The \(\href{../syntax/modules.html#syntax-func}{\mathsf{locals}}\) declare a vector of mutable local variables and their types. These variables are referenced through local indices in the function’s body. The index of the first local is the smallest index not referencing a parameter.

The \(\href{../syntax/modules.html#syntax-func}{\mathsf{body}}\) is an instruction sequence that upon termination must produce a stack matching the function type’s result type.

Functions are referenced through function indices, starting with the smallest index not referencing a function import.

Tables¶

The \(\href{../syntax/modules.html#syntax-module}{\mathsf{tables}}\) component of a module defines a vector of tables described by their table type:

\[\begin{split}\begin{array}{llll} \def\mathdef1558#1{{}}\mathdef1558{table} & \href{../syntax/modules.html#syntax-table}{\mathit{table}} &::=& \{ \href{../syntax/modules.html#syntax-table}{\mathsf{type}}~\href{../syntax/types.html#syntax-tabletype}{\mathit{tabletype}} \} \\ \end{array}\end{split}\]

A table is a vector of opaque values of a particular table element type. The \(\href{../syntax/types.html#syntax-limits}{\mathsf{min}}\) size in the limits of the table type specifies the initial size of that table, while its \(\href{../syntax/types.html#syntax-limits}{\mathsf{max}}\), if present, restricts the size to which it can grow later.

Tables can be initialized through element segments.

Tables are referenced through table indices, starting with the smallest index not referencing a table import. Most constructs implicitly reference table index \(0\).

Note

In the current version of WebAssembly, at most one table may be defined or imported in a single module, and all constructs implicitly reference this table \(0\). This restriction may be lifted in future versions.

Memories¶

The \(\href{../syntax/modules.html#syntax-module}{\mathsf{mems}}\) component of a module defines a vector of linear memories (or memories for short) as described by their memory type:

\[\begin{split}\begin{array}{llll} \def\mathdef1558#1{{}}\mathdef1558{memory} & \href{../syntax/modules.html#syntax-mem}{\mathit{mem}} &::=& \{ \href{../syntax/modules.html#syntax-mem}{\mathsf{type}}~\href{../syntax/types.html#syntax-memtype}{\mathit{memtype}} \} \\ \end{array}\end{split}\]

A memory is a vector of raw uninterpreted bytes. The \(\href{../syntax/types.html#syntax-limits}{\mathsf{min}}\) size in the limits of the memory type specifies the initial size of that memory, while its \(\href{../syntax/types.html#syntax-limits}{\mathsf{max}}\), if present, restricts the size to which it can grow later. Both are in units of page size.

Memories can be initialized through data segments.

Memories are referenced through memory indices, starting with the smallest index not referencing a memory import. Most constructs implicitly reference memory index \(0\).

Note

In the current version of WebAssembly, at most one memory may be defined or imported in a single module, and all constructs implicitly reference this memory \(0\). This restriction may be lifted in future versions.

Globals¶

The \(\href{../syntax/modules.html#syntax-module}{\mathsf{globals}}\) component of a module defines a vector of global variables (or globals for short):

\[\begin{split}\begin{array}{llll} \def\mathdef1558#1{{}}\mathdef1558{global} & \href{../syntax/modules.html#syntax-global}{\mathit{global}} &::=& \{ \href{../syntax/modules.html#syntax-global}{\mathsf{type}}~\href{../syntax/types.html#syntax-globaltype}{\mathit{globaltype}}, \href{../syntax/modules.html#syntax-global}{\mathsf{init}}~\href{../syntax/instructions.html#syntax-expr}{\mathit{expr}} \} \\ \end{array}\end{split}\]

Each global stores a single value of the given global type. Its \(\href{../syntax/modules.html#syntax-global}{\mathsf{type}}\) also specifies whether a global is immutable or mutable. Moreover, each global is initialized with an \(\href{../syntax/modules.html#syntax-global}{\mathsf{init}}\) value given by a constant initializer expression.

Globals are referenced through global indices, starting with the smallest index not referencing a global import.

Element Segments¶

The initial contents of a table is uninitialized. The \(\href{../syntax/modules.html#syntax-module}{\mathsf{elem}}\) component of a module defines a vector of element segments that initialize a subrange of a table, at a given offset, from a static vector of elements.

\[\begin{split}\begin{array}{llll} \def\mathdef1558#1{{}}\mathdef1558{element segment} & \href{../syntax/modules.html#syntax-elem}{\mathit{elem}} &::=& \{ \href{../syntax/modules.html#syntax-elem}{\mathsf{table}}~\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}, \href{../syntax/modules.html#syntax-elem}{\mathsf{offset}}~\href{../syntax/instructions.html#syntax-expr}{\mathit{expr}}, \href{../syntax/modules.html#syntax-elem}{\mathsf{init}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}}) \} \\ \end{array}\end{split}\]

The \(\href{../syntax/modules.html#syntax-elem}{\mathsf{offset}}\) is given by a constant expression.

Note

In the current version of WebAssembly, at most one table is allowed in a module. Consequently, the only valid \(\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}\) is \(0\).

Data Segments¶

The initial contents of a memory are zero-valued bytes. The \(\href{../syntax/modules.html#syntax-module}{\mathsf{data}}\) component of a module defines a vector of data segments that initialize a range of memory, at a given offset, with a static vector of bytes.

\[\begin{split}\begin{array}{llll} \def\mathdef1558#1{{}}\mathdef1558{data segment} & \href{../syntax/modules.html#syntax-data}{\mathit{data}} &::=& \{ \href{../syntax/modules.html#syntax-data}{\mathsf{data}}~\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}, \href{../syntax/modules.html#syntax-data}{\mathsf{offset}}~\href{../syntax/instructions.html#syntax-expr}{\mathit{expr}}, \href{../syntax/modules.html#syntax-data}{\mathsf{init}}~\href{../syntax/conventions.html#syntax-vec}{\mathit{vec}}(\href{../syntax/values.html#syntax-byte}{\mathit{byte}}) \} \\ \end{array}\end{split}\]

The \(\href{../syntax/modules.html#syntax-data}{\mathsf{offset}}\) is given by a constant expression.

Note

In the current version of WebAssembly, at most one memory is allowed in a module. Consequently, the only valid \(\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}\) is \(0\).

Start Function¶

The \(\href{../syntax/modules.html#syntax-module}{\mathsf{start}}\) component of a module declares the function index of a start function that is automatically invoked when the module is instantiated, after tables and memories have been initialized.

\[\begin{split}\begin{array}{llll} \def\mathdef1558#1{{}}\mathdef1558{start function} & \href{../syntax/modules.html#syntax-start}{\mathit{start}} &::=& \{ \href{../syntax/modules.html#syntax-start}{\mathsf{func}}~\href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}} \} \\ \end{array}\end{split}\]

Note

The start function is intended for initializing the state of a module. The module and its exports are not accessible before this initialization has completed.

Exports¶

The \(\href{../syntax/modules.html#syntax-module}{\mathsf{exports}}\) component of a module defines a set of exports that become accessible to the host environment once the module has been instantiated.

\[\begin{split}\begin{array}{llcl} \def\mathdef1558#1{{}}\mathdef1558{export} & \href{../syntax/modules.html#syntax-export}{\mathit{export}} &::=& \{ \href{../syntax/modules.html#syntax-export}{\mathsf{name}}~\href{../syntax/values.html#syntax-name}{\mathit{name}}, \href{../syntax/modules.html#syntax-export}{\mathsf{desc}}~\href{../syntax/modules.html#syntax-exportdesc}{\mathit{exportdesc}} \} \\ \def\mathdef1558#1{{}}\mathdef1558{export description} & \href{../syntax/modules.html#syntax-exportdesc}{\mathit{exportdesc}} &::=& \href{../syntax/modules.html#syntax-exportdesc}{\mathsf{func}}~\href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}} \\&&|& \href{../syntax/modules.html#syntax-exportdesc}{\mathsf{table}}~\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}} \\&&|& \href{../syntax/modules.html#syntax-exportdesc}{\mathsf{mem}}~\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}} \\&&|& \href{../syntax/modules.html#syntax-exportdesc}{\mathsf{global}}~\href{../syntax/modules.html#syntax-globalidx}{\mathit{globalidx}} \\ \end{array}\end{split}\]

Each export is labeled by a unique name. Exportable definitions are functions, tables, memories, and globals, which are referenced through a respective descriptor.

Conventions¶

The following auxiliary notation is defined for sequences of exports, filtering out indices of a specific kind in an order-preserving fashion:

\(\href{../syntax/modules.html#syntax-exportdesc}{\mathrm{funcs}}(\href{../syntax/modules.html#syntax-export}{\mathit{export}}^\ast) = [\href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}} ~|~ \href{../syntax/modules.html#syntax-exportdesc}{\mathsf{func}}~\href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}} \in (\href{../syntax/modules.html#syntax-export}{\mathit{export}}.\href{../syntax/modules.html#syntax-export}{\mathsf{desc}})^\ast]\)
\(\href{../syntax/modules.html#syntax-exportdesc}{\mathrm{tables}}(\href{../syntax/modules.html#syntax-export}{\mathit{export}}^\ast) = [\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}} ~|~ \href{../syntax/modules.html#syntax-exportdesc}{\mathsf{table}}~\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}} \in (\href{../syntax/modules.html#syntax-export}{\mathit{export}}.\href{../syntax/modules.html#syntax-export}{\mathsf{desc}})^\ast]\)
\(\href{../syntax/modules.html#syntax-exportdesc}{\mathrm{mems}}(\href{../syntax/modules.html#syntax-export}{\mathit{export}}^\ast) = [\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}} ~|~ \href{../syntax/modules.html#syntax-exportdesc}{\mathsf{mem}}~\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}} \in (\href{../syntax/modules.html#syntax-export}{\mathit{export}}.\href{../syntax/modules.html#syntax-export}{\mathsf{desc}})^\ast]\)
\(\href{../syntax/modules.html#syntax-exportdesc}{\mathrm{globals}}(\href{../syntax/modules.html#syntax-export}{\mathit{export}}^\ast) = [\href{../syntax/modules.html#syntax-globalidx}{\mathit{globalidx}} ~|~ \href{../syntax/modules.html#syntax-exportdesc}{\mathsf{global}}~\href{../syntax/modules.html#syntax-globalidx}{\mathit{globalidx}} \in (\href{../syntax/modules.html#syntax-export}{\mathit{export}}.\href{../syntax/modules.html#syntax-export}{\mathsf{desc}})^\ast]\)

Imports¶

The \(\href{../syntax/modules.html#syntax-module}{\mathsf{imports}}\) component of a module defines a set of imports that are required for instantiation.

\[\begin{split}\begin{array}{llll} \def\mathdef1558#1{{}}\mathdef1558{import} & \href{../syntax/modules.html#syntax-import}{\mathit{import}} &::=& \{ \href{../syntax/modules.html#syntax-import}{\mathsf{module}}~\href{../syntax/values.html#syntax-name}{\mathit{name}}, \href{../syntax/modules.html#syntax-import}{\mathsf{name}}~\href{../syntax/values.html#syntax-name}{\mathit{name}}, \href{../syntax/modules.html#syntax-import}{\mathsf{desc}}~\href{../syntax/modules.html#syntax-importdesc}{\mathit{importdesc}} \} \\ \def\mathdef1558#1{{}}\mathdef1558{import description} & \href{../syntax/modules.html#syntax-importdesc}{\mathit{importdesc}} &::=& \href{../syntax/modules.html#syntax-importdesc}{\mathsf{func}}~\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}} \\&&|& \href{../syntax/modules.html#syntax-importdesc}{\mathsf{table}}~\href{../syntax/types.html#syntax-tabletype}{\mathit{tabletype}} \\&&|& \href{../syntax/modules.html#syntax-importdesc}{\mathsf{mem}}~\href{../syntax/types.html#syntax-memtype}{\mathit{memtype}} \\&&|& \href{../syntax/modules.html#syntax-importdesc}{\mathsf{global}}~\href{../syntax/types.html#syntax-globaltype}{\mathit{globaltype}} \\ \end{array}\end{split}\]

Each import is labeled by a two-level name space, consisting of a \(\href{../syntax/modules.html#syntax-import}{\mathsf{module}}\) name and a \(\href{../syntax/modules.html#syntax-import}{\mathsf{name}}\) for an entity within that module. Importable definitions are functions, tables, memories, and globals. Each import is specified by a descriptor with a respective type that a definition provided during instantiation is required to match.

Every import defines an index in the respective index space. In each index space, the indices of imports go before the first index of any definition contained in the module itself.

Note

Unlike export names, import names are not necessarily unique. It is possible to import the same \(\href{../syntax/modules.html#syntax-import}{\mathsf{module}}\)/\(\href{../syntax/modules.html#syntax-import}{\mathsf{name}}\) pair multiple times; such imports may even have different type descriptions, including different kinds of entities. A module with such imports can still be instantiated depending on the specifics of how an embedder allows resolving and supplying imports. However, embedders are not required to support such overloading, and a WebAssembly module itself cannot implement an overloaded name.