Custom Sections and Annotations¶
This appendix defines dedicated custom sections for WebAssembly’s binary format and annotations for the text format. Such sections or annotations do not contribute to, or otherwise affect, the WebAssembly semantics, and may be ignored by an implementation. However, they provide useful meta data that implementations can make use of to improve user experience or take compilation hints.
Name Section¶
The name section is a custom section whose name string is itself \(\def\mathdef118#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef118{name}\). The name section should appear only once in a module, and only after the data section.
The purpose of this section is to attach printable names to definitions in a module, which e.g. can be used by a debugger or when parts of the module are to be rendered in text form.
Subsections¶
The data of a name section consists of a sequence of subsections. Each subsection consists of a
a one-byte subsection id,
the \(\href{../syntax/values.html#syntax-int}{\mathit{u32}}\) size of the contents, in bytes,
the actual contents, whose structure is dependent on the subsection id.
The following subsection ids are used:
Id |
Subsection |
|---|---|
0 |
|
1 |
|
2 |
Each subsection may occur at most once, and in order of increasing id.
Name Maps¶
A name map assigns names to indices in a given index space. It consists of a vector of index/name pairs in order of increasing index value. Each index must be unique, but the assigned names need not be.
An indirect name map assigns names to a two-dimensional index space, where secondary indices are grouped by primary indices. It consists of a vector of primary index/name map pairs in order of increasing index value, where each name map in turn maps secondary indices to names. Each primary index must be unique, and likewise each secondary index per individual name map.
Module Names¶
The module name subsection has the id 0. It simply consists of a single name that is assigned to the module itself.
Function Names¶
The function name subsection has the id 1. It consists of a name map assigning function names to function indices.
Local Names¶
The local name subsection has the id 2. It consists of an indirect name map assigning local names to local indices grouped by function indices.
Name Annotations¶
Name annotations are the textual analogue to the name section and provide a textual representation for it. Consequently, their id is \(\mathtt{@name}\).
Analogous to the name section, name annotations are allowed on modules, functions, and locals (including parameters). They can be placed where the text format allows binding occurrences of respective identifiers. If both an identifier and a name annotation are given, the annotation is expected after the identifier. In that case, the annotation takes precedence over the identifier as a textual representation of the binding’s name. At most one name annotation may be given per binding.
All name annotations have the following format:
Note
All name annotations can be arbitrary UTF-8 strings. Names need not be unique.
Module Names¶
A module name annotation must be placed on a module definition, directly after the \(\def\mathdef122#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef122{module}\) keyword, or if present, after the following module identifier.
Function Names¶
A function name annotation must be placed on a function definition or function import, directly after the \(\def\mathdef123#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef123{func}\) keyword, or if present, after the following function identifier or.
Parameter Names¶
A parameter name annotation must be placed on a parameter declaration, directly after the \(\def\mathdef124#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef124{param}\) keyword, or if present, after the following parameter identifier. It may only be placed on a declaration that declares exactly one parameter.
Local Names¶
A local name annotation must be placed on a local declaration, directly after the \(\def\mathdef125#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef125{local}\) keyword, or if present, after the following local identifier. It may only be placed on a declaration that declares exactly one local.
Custom Annotations¶
Custom annotations are a generic textual representation for any custom section. Their id is \(\mathtt{@custom}\). By generating custom annotations, tools converting between binary format and text format can maintain and round-trip the content of custom sections even when they do not recognize them.
Custom annotations must be placed inside a module definition. They must occur anywhere after the \(\def\mathdef126#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef126{module}\) keyword, or if present, after the following module identifier. They must not be nested into other constructs.
The first string in a custom annotation denotes the name of the custom section it represents. The remaining strings collectively represent the section’s payload data, written as a data string, which can be split up into a possibly empty sequence of individual string literals (similar to data segments).
An arbitrary number of custom annotations (even of the same name) may occur in a module, each defining a separate custom section when converting to binary format. Placement of the sections in the binary can be customized via explicit placement directives, that position them either directly before or directly after a known section. That section must exist and be non-empty in the binary encoding of the annotated module. The placements \(\mathtt{(before~first)}\) and \(\mathtt{(after~last)}\) denote virtual sections before the first and after the last known section, respectively. When the placement directive is omitted, it defaults to \(\mathtt{(after~last)}\).
If multiple placement directives appear for the same position, then the sections are all placed there, in order of their appearance in the text. For this purpose, the position \(\mathtt{after}\) a section is considered different from the position \(\mathtt{before}\) the consecutive section, and the former occurs before the latter.
Note
Future versions of WebAssembly may introduce additional sections between others or at the beginning or end of a module. Using \(\mathtt{first}\) and \(\mathtt{last}\) guarantees that placement will still go before or after any future section, respectively.
If a custom section with a specific section id is given as well as annotations representing the same custom section (e.g., \(\mathtt{@name}\) annotations as well as a \(\mathtt{@custom}\) annotation for a \(\mathtt{name}\) section), then two sections are assumed to be created. Their relative placement will depend on the placement directive given for the \(\mathtt{@custom}\) annotation as well as the implicit placement requirements of the custom section, which are applied to the other annotation.
Note
For example, the following module,
(module
(@custom "A" "aaa")
(type $t (func))
(@custom "B" (after func) "bbb")
(@custom "C" (before func) "ccc")
(@custom "D" (after last) "ddd")
(table 10 funcref)
(func (type $t))
(@custom "E" (after import) "eee")
(@custom "F" (before type) "fff")
(@custom "G" (after data) "ggg")
(@custom "H" (after code) "hhh")
(@custom "I" (after func) "iii")
(@custom "J" (before func) "jjj")
(@custom "K" (before first) "kkk")
)
will result in the following section ordering:
custom section "K"
custom section "F"
type section
custom section "E"
custom section "C"
custom section "J"
function section
custom section "B"
custom section "I"
table section
code section
custom section "H"
custom section "G"
custom section "A"
custom section "D"