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, tags, and globals. In addition, it can declare imports and exports and provide initialization in the form of data and element segments, or a start function.

\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/modules.html#syntax-module}{\mathit{module}}} & ::= & \href{../syntax/modules.html#syntax-module}{\mathsf{module}}~{{\href{../syntax/types.html#syntax-rectype}{\mathit{type}}}^\ast}~{{\href{../syntax/modules.html#syntax-import}{\mathit{import}}}^\ast}~{{\href{../syntax/modules.html#syntax-func}{\mathit{func}}}^\ast}~{{\href{../syntax/modules.html#syntax-global}{\mathit{global}}}^\ast}~{{\href{../syntax/modules.html#syntax-table}{\mathit{table}}}^\ast}~{{\href{../syntax/modules.html#syntax-mem}{\mathit{mem}}}^\ast}~{{\href{../syntax/modules.html#syntax-tag}{\mathit{tag}}}^\ast}~{{\href{../syntax/modules.html#syntax-elem}{\mathit{elem}}}^\ast}~{{\href{../syntax/modules.html#syntax-data}{\mathit{data}}}^\ast}~{{\href{../syntax/modules.html#syntax-start}{\mathit{start}}}^?}~{{\href{../syntax/modules.html#syntax-export}{\mathit{export}}}^\ast} \\ \end{array}\end{split}\]

Each of the lists — 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}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}} & ::= & {\href{../syntax/modules.html#syntax-idx}{\mathit{idx}}} \\ & {\href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}}} & ::= & {\href{../syntax/modules.html#syntax-idx}{\mathit{idx}}} \\ & {\href{../syntax/modules.html#syntax-globalidx}{\mathit{globalidx}}} & ::= & {\href{../syntax/modules.html#syntax-idx}{\mathit{idx}}} \\ & {\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}} & ::= & {\href{../syntax/modules.html#syntax-idx}{\mathit{idx}}} \\ & {\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}} & ::= & {\href{../syntax/modules.html#syntax-idx}{\mathit{idx}}} \\ & {\href{../syntax/modules.html#syntax-tagidx}{\mathit{tagidx}}} & ::= & {\href{../syntax/modules.html#syntax-idx}{\mathit{idx}}} \\ & {\href{../syntax/modules.html#syntax-elemidx}{\mathit{elemidx}}} & ::= & {\href{../syntax/modules.html#syntax-idx}{\mathit{idx}}} \\ & {\href{../syntax/modules.html#syntax-dataidx}{\mathit{dataidx}}} & ::= & {\href{../syntax/modules.html#syntax-idx}{\mathit{idx}}} \\ & {\href{../syntax/modules.html#syntax-labelidx}{\mathit{labelidx}}} & ::= & {\href{../syntax/modules.html#syntax-idx}{\mathit{idx}}} \\ & {\href{../syntax/modules.html#syntax-localidx}{\mathit{localidx}}} & ::= & {\href{../syntax/modules.html#syntax-idx}{\mathit{idx}}} \\ & {\href{../syntax/modules.html#syntax-fieldidx}{\mathit{fieldidx}}} & ::= & {\href{../syntax/modules.html#syntax-idx}{\mathit{idx}}} \\ \end{array}\end{split}\]

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

Element indices reference element segments and data indices reference data segments.

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.

Each aggregate type provides an index space for its fields.

Conventions¶

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

For every index space \({\mathit{abcidx}}\), the notation \({\mathrm{abcidx}}(A)\) denotes the set of indices from that index space occurring free in \(A\). Sometimes this set is reinterpreted as the list of its elements.

Note

For example, if \({{\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}}^\ast}\) is \((\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{data{.}drop}}~1)~(\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{memory{.}init}}~2~3)\), then \({\mathrm{dataidx}}_{\mathit{instrs}}({{\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}}^\ast}) = 1~3\), or equivalently, the set \(\{ 1, 3 \}\).

Types¶

The \({\href{../syntax/types.html#syntax-rectype}{\mathit{type}}}\) section of a module defines a list of recursive types, each consisting of a list of sub types referenced by individual type indices. All function or aggregate types used in a module must be defined in this section.

\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/types.html#syntax-rectype}{\mathit{type}}} & ::= & \href{../syntax/modules.html#syntax-type}{\mathsf{type}}~{\href{../syntax/types.html#syntax-rectype}{\mathit{rectype}}} \\ \end{array}\end{split}\]

Functions¶

The \({\href{../syntax/modules.html#syntax-func}{\mathit{func}}}\) section of a module defines a list of functions with the following structure:

\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/modules.html#syntax-func}{\mathit{func}}} & ::= & \href{../syntax/modules.html#syntax-func}{\mathsf{func}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}}~{{\href{../syntax/modules.html#syntax-local}{\mathit{local}}}^\ast}~{\href{../syntax/instructions.html#syntax-expr}{\mathit{expr}}} \\ & {\href{../syntax/modules.html#syntax-local}{\mathit{local}}} & ::= & \href{../syntax/modules.html#syntax-local}{\mathsf{local}}~{\href{../syntax/types.html#syntax-valtype}{\mathit{valtype}}} \\ \end{array}\end{split}\]

The type index of a function declares its signature by reference to a function 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 locals declare a list 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.

A function’s expression is an instruction sequence that represents the body of the function. Upon termination it 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-table}{\mathit{table}}}\) section of a module defines a list of tables described by their table type:

\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/modules.html#syntax-table}{\mathit{table}}} & ::= & \href{../syntax/modules.html#syntax-table}{\mathsf{table}}~{\href{../syntax/types.html#syntax-tabletype}{\mathit{tabletype}}}~{\href{../syntax/instructions.html#syntax-expr}{\mathit{expr}}} \\ \end{array}\end{split}\]

A table is an array of opaque values of a particular reference type that is specified by the table type. Each table slot is initialized with a value given by a constant initializer expression. Tables can further be initialized through element segments.

The minimum size in the limits of the table type specifies the initial size of that table, while its maximum restricts the size to which it can grow later.

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

Memories¶

The \({\href{../syntax/modules.html#syntax-mem}{\mathit{mem}}}\) section of a module defines a list of linear memories (or memories for short) as described by their memory type:

\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/modules.html#syntax-mem}{\mathit{mem}}} & ::= & \href{../syntax/modules.html#syntax-mem}{\mathsf{memory}}~{\href{../syntax/types.html#syntax-memtype}{\mathit{memtype}}} \\ \end{array}\end{split}\]

A memory is a list of raw uninterpreted bytes. The minimum size in the limits of its memory type specifies the initial size of that memory, while its maximum, 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\).

Globals¶

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

\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/modules.html#syntax-global}{\mathit{global}}} & ::= & \href{../syntax/modules.html#syntax-global}{\mathsf{global}}~{\href{../syntax/types.html#syntax-globaltype}{\mathit{globaltype}}}~{\href{../syntax/instructions.html#syntax-expr}{\mathit{expr}}} \\ \end{array}\end{split}\]

Each global stores a single value of the type specified in the global type. It also specifies whether a global is immutable or mutable. Moreover, each global is initialized with a value given by a constant initializer expression.

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

Tags¶

The \({\href{../syntax/modules.html#syntax-tag}{\mathit{tag}}}\) section of a module defines a list of tags:

\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/modules.html#syntax-tag}{\mathit{tag}}} & ::= & \href{../syntax/modules.html#syntax-tag}{\mathsf{tag}}~{\href{../syntax/modules.html#syntax-typeidx}{\mathit{typeidx}}} \\ \end{array}\end{split}\]

The type index of a tag must refer to a function type that declares its tag type.

Tags are referenced through tag indices, starting with the smallest index not referencing a tag import.

Element Segments¶

The \({\href{../syntax/modules.html#syntax-elem}{\mathit{elem}}}\) section of a module defines a list of element segments, which can be used to initialize a subrange of a table from a static list of elements.

\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/modules.html#syntax-elem}{\mathit{elem}}} & ::= & \href{../syntax/modules.html#syntax-elem}{\mathsf{elem}}~{\href{../syntax/types.html#syntax-reftype}{\mathit{reftype}}}~{{\href{../syntax/instructions.html#syntax-expr}{\mathit{expr}}}^\ast}~{\href{../syntax/modules.html#syntax-elemmode}{\mathit{elemmode}}} \\ & {\href{../syntax/modules.html#syntax-elemmode}{\mathit{elemmode}}} & ::= & \href{../syntax/modules.html#syntax-elemmode}{\mathsf{active}}~{\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}}~{\href{../syntax/instructions.html#syntax-expr}{\mathit{expr}}} ~|~ \href{../syntax/modules.html#syntax-elemmode}{\mathsf{passive}} ~|~ \href{../syntax/modules.html#syntax-elemmode}{\mathsf{declare}} \\ \end{array}\end{split}\]

Each element segment defines a reference type and a corresponding list of constant element expressions.

Element segments have a mode that identifies them as either active, passive, or declarative. A passive element segment’s elements can be copied to a table using the \(\mathsf{table{.}init}\) instruction. An active element segment copies its elements into a table during instantiation, as specified by a table index and a constant expression defining an offset into that table. A declarative element segment is not available at runtime but merely serves to forward-declare references that are formed in code with instructions like \(\mathsf{ref{.}func}\). The offset is given by another constant expression.

Element segments are referenced through element indices.

Data Segments¶

The \({\href{../syntax/modules.html#syntax-data}{\mathit{data}}}\) section of a module defines a list of data segments, which can be used to initialize a range of memory from a static list of bytes.

\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/modules.html#syntax-data}{\mathit{data}}} & ::= & \href{../syntax/modules.html#syntax-data}{\mathsf{data}}~{{\href{../syntax/values.html#syntax-byte}{\mathit{byte}}}^\ast}~{\href{../syntax/modules.html#syntax-datamode}{\mathit{datamode}}} \\ & {\href{../syntax/modules.html#syntax-datamode}{\mathit{datamode}}} & ::= & \href{../syntax/modules.html#syntax-datamode}{\mathsf{active}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}}~{\href{../syntax/instructions.html#syntax-expr}{\mathit{expr}}} ~|~ \href{../syntax/modules.html#syntax-datamode}{\mathsf{passive}} \\ \end{array}\end{split}\]

Similar to element segments, data segments have a mode that identifies them as either active or passive. A passive data segment’s contents can be copied into a memory using the \(\mathsf{memory{.}init}\) instruction. An active data segment copies its contents into a memory during instantiation, as specified by a memory index and a constant expression defining an offset into that memory.

Data segments are referenced through data indices.

Start Function¶

The \({\href{../syntax/modules.html#syntax-start}{\mathit{start}}}\) section 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}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/modules.html#syntax-start}{\mathit{start}}} & ::= & \href{../syntax/modules.html#syntax-start}{\mathsf{start}}~{\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 externally before this initialization has completed.

Exports¶

The \({\href{../syntax/modules.html#syntax-export}{\mathit{export}}}\) section 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}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/modules.html#syntax-export}{\mathit{export}}} & ::= & \href{../syntax/modules.html#syntax-export}{\mathsf{export}}~{\href{../syntax/values.html#syntax-name}{\mathit{name}}}~{\href{../syntax/modules.html#syntax-externidx}{\mathit{externidx}}} \\[0.8ex] & {\href{../syntax/modules.html#syntax-externidx}{\mathit{externidx}}} & ::= & \href{../syntax/modules.html#syntax-externidx}{\mathsf{func}}~{\href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}}} ~|~ \href{../syntax/modules.html#syntax-externidx}{\mathsf{global}}~{\href{../syntax/modules.html#syntax-globalidx}{\mathit{globalidx}}} ~|~ \href{../syntax/modules.html#syntax-externidx}{\mathsf{table}}~{\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}}} ~|~ \href{../syntax/modules.html#syntax-externidx}{\mathsf{memory}}~{\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}} ~|~ \href{../syntax/modules.html#syntax-externidx}{\mathsf{tag}}~{\href{../syntax/modules.html#syntax-tagidx}{\mathit{tagidx}}} \\ \end{array}\end{split}\]

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

Conventions¶

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

\[\begin{split}\begin{array}[t]{@{}lcl@{}l@{}} {\href{../syntax/modules.html#syntax-externidx}{\mathrm{funcs}}}(\epsilon) & = & \epsilon \\ {\href{../syntax/modules.html#syntax-externidx}{\mathrm{funcs}}}((\href{../syntax/modules.html#syntax-externidx}{\mathsf{func}}~x)~{{\mathit{xx}}^\ast}) & = & x~{\href{../syntax/modules.html#syntax-externidx}{\mathrm{funcs}}}({{\mathit{xx}}^\ast}) \\ {\href{../syntax/modules.html#syntax-externidx}{\mathrm{funcs}}}({\href{../syntax/modules.html#syntax-externidx}{\mathit{externidx}}}~{{\mathit{xx}}^\ast}) & = & {\href{../syntax/modules.html#syntax-externidx}{\mathrm{funcs}}}({{\mathit{xx}}^\ast}) & \mbox{otherwise} \\[0.8ex] {\href{../syntax/modules.html#syntax-externidx}{\mathrm{tables}}}(\epsilon) & = & \epsilon \\ {\href{../syntax/modules.html#syntax-externidx}{\mathrm{tables}}}((\href{../syntax/modules.html#syntax-externidx}{\mathsf{table}}~x)~{{\mathit{xx}}^\ast}) & = & x~{\href{../syntax/modules.html#syntax-externidx}{\mathrm{tables}}}({{\mathit{xx}}^\ast}) \\ {\href{../syntax/modules.html#syntax-externidx}{\mathrm{tables}}}({\href{../syntax/modules.html#syntax-externidx}{\mathit{externidx}}}~{{\mathit{xx}}^\ast}) & = & {\href{../syntax/modules.html#syntax-externidx}{\mathrm{tables}}}({{\mathit{xx}}^\ast}) & \mbox{otherwise} \\[0.8ex] {\href{../syntax/modules.html#syntax-externidx}{\mathrm{mems}}}(\epsilon) & = & \epsilon \\ {\href{../syntax/modules.html#syntax-externidx}{\mathrm{mems}}}((\href{../syntax/modules.html#syntax-externidx}{\mathsf{memory}}~x)~{{\mathit{xx}}^\ast}) & = & x~{\href{../syntax/modules.html#syntax-externidx}{\mathrm{mems}}}({{\mathit{xx}}^\ast}) \\ {\href{../syntax/modules.html#syntax-externidx}{\mathrm{mems}}}({\href{../syntax/modules.html#syntax-externidx}{\mathit{externidx}}}~{{\mathit{xx}}^\ast}) & = & {\href{../syntax/modules.html#syntax-externidx}{\mathrm{mems}}}({{\mathit{xx}}^\ast}) & \mbox{otherwise} \\[0.8ex] {\href{../syntax/modules.html#syntax-externidx}{\mathrm{globals}}}(\epsilon) & = & \epsilon \\ {\href{../syntax/modules.html#syntax-externidx}{\mathrm{globals}}}((\href{../syntax/modules.html#syntax-externidx}{\mathsf{global}}~x)~{{\mathit{xx}}^\ast}) & = & x~{\href{../syntax/modules.html#syntax-externidx}{\mathrm{globals}}}({{\mathit{xx}}^\ast}) \\ {\href{../syntax/modules.html#syntax-externidx}{\mathrm{globals}}}({\href{../syntax/modules.html#syntax-externidx}{\mathit{externidx}}}~{{\mathit{xx}}^\ast}) & = & {\href{../syntax/modules.html#syntax-externidx}{\mathrm{globals}}}({{\mathit{xx}}^\ast}) & \mbox{otherwise} \\[0.8ex] {\href{../syntax/modules.html#syntax-externidx}{\mathrm{tags}}}(\epsilon) & = & \epsilon \\ {\href{../syntax/modules.html#syntax-externidx}{\mathrm{tags}}}((\href{../syntax/modules.html#syntax-externidx}{\mathsf{tag}}~x)~{{\mathit{xx}}^\ast}) & = & x~{\href{../syntax/modules.html#syntax-externidx}{\mathrm{tags}}}({{\mathit{xx}}^\ast}) \\ {\href{../syntax/modules.html#syntax-externidx}{\mathrm{tags}}}({\href{../syntax/modules.html#syntax-externidx}{\mathit{externidx}}}~{{\mathit{xx}}^\ast}) & = & {\href{../syntax/modules.html#syntax-externidx}{\mathrm{tags}}}({{\mathit{xx}}^\ast}) & \mbox{otherwise} \\ \end{array}\end{split}\]

Imports¶

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

\[\begin{split}\begin{array}[t]{@{}l@{}rrl@{}l@{}} & {\href{../syntax/modules.html#syntax-import}{\mathit{import}}} & ::= & \href{../syntax/modules.html#syntax-import}{\mathsf{import}}~{\href{../syntax/values.html#syntax-name}{\mathit{name}}}~{\href{../syntax/values.html#syntax-name}{\mathit{name}}}~{\href{../syntax/types.html#syntax-externtype}{\mathit{externtype}}} \\ \end{array}\end{split}\]

Each import is labeled by a two-level name space, consisting of a module name and an item name for an entity within that module. Importable definitions are functions, tables, memories, globals, and tags. Each import is specified by a respective external 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 module/item 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.