Name Section
The name section is a custom section whose name string is itself \(\def\mathdef122#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef122{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.
Note
All names are represented in Unicode encoded in UTF-8.
Names need not be unique.
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.
\[\begin{split}\begin{array}{llcll}
\def\mathdef83#1{{}}\mathdef83{name section} & \href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesec}} &::=&
\href{../binary/modules.html#binary-section}{\mathtt{section}}_0(\href{../appendix/custom.html#binary-namesubsection}{\mathtt{namedata}}) \\
\def\mathdef83#1{{}}\mathdef83{name data} & \href{../appendix/custom.html#binary-namesubsection}{\mathtt{namedata}} &::=&
n{:}\href{../binary/values.html#binary-name}{\mathtt{name}} & (\mathrel{\mbox{if}} n = \def\mathdef123#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef123{name}) \\ &&&
\href{../appendix/custom.html#binary-modulenamesec}{\mathtt{modulenamesubsec}}^? \\ &&&
\href{../appendix/custom.html#binary-funcnamesec}{\mathtt{funcnamesubsec}}^? \\ &&&
\href{../appendix/custom.html#binary-localnamesec}{\mathtt{localnamesubsec}}^? \\ &&&
\href{../appendix/custom.html#binary-tagnamesec}{\mathtt{tagnamesubsec}}^? \\
\def\mathdef83#1{{}}\mathdef83{name subsection} & \href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}_N(\mathtt{B}) &::=&
N{:}\href{../binary/values.html#binary-byte}{\mathtt{byte}}~~\mathit{size}{:}\href{../binary/values.html#binary-int}{\def\mathdef88#1{{\mathtt{u}#1}}\mathdef88{\mathtt{32}}}~~\mathtt{B}
& (\mathrel{\mbox{if}} \mathit{size} = ||\mathtt{B}||) \\
\end{array}\end{split}\]
The following subsection ids are used:
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.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{name map} & \href{../appendix/custom.html#binary-namemap}{\mathtt{namemap}} &::=&
\href{../binary/conventions.html#binary-vec}{\mathtt{vec}}(\href{../appendix/custom.html#binary-namemap}{\mathtt{nameassoc}}) \\
\def\mathdef83#1{{}}\mathdef83{name association} & \href{../appendix/custom.html#binary-namemap}{\mathtt{nameassoc}} &::=&
\href{../binary/modules.html#binary-index}{\mathtt{idx}}~\href{../binary/values.html#binary-name}{\mathtt{name}} \\
\end{array}\end{split}\]
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.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{indirect name map} & \href{../appendix/custom.html#binary-indirectnamemap}{\mathtt{indirectnamemap}} &::=&
\href{../binary/conventions.html#binary-vec}{\mathtt{vec}}(\href{../appendix/custom.html#binary-indirectnamemap}{\mathtt{indirectnameassoc}}) \\
\def\mathdef83#1{{}}\mathdef83{indirect name association} & \href{../appendix/custom.html#binary-indirectnamemap}{\mathtt{indirectnameassoc}} &::=&
\href{../binary/modules.html#binary-index}{\mathtt{idx}}~\href{../appendix/custom.html#binary-namemap}{\mathtt{namemap}} \\
\end{array}\end{split}\]
Module Names
The module name subsection has the id 0.
It simply consists of a single name that is assigned to the module itself.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{module name subsection} & \href{../appendix/custom.html#binary-modulenamesec}{\mathtt{modulenamesubsec}} &::=&
\href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}_0(\href{../binary/values.html#binary-name}{\mathtt{name}}) \\
\end{array}\end{split}\]
Function Names
The function name subsection has the id 1.
It consists of a name map assigning function names to function indices.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{function name subsection} & \href{../appendix/custom.html#binary-funcnamesec}{\mathtt{funcnamesubsec}} &::=&
\href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}_1(\href{../appendix/custom.html#binary-namemap}{\mathtt{namemap}}) \\
\end{array}\end{split}\]
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.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{local name subsection} & \href{../appendix/custom.html#binary-localnamesec}{\mathtt{localnamesubsec}} &::=&
\href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}_2(\href{../appendix/custom.html#binary-indirectnamemap}{\mathtt{indirectnamemap}}) \\
\end{array}\end{split}\]
Type Names
The type name subsection has the id 4.
It consists of a name map assigning type names to type indices.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{type name subsection} & \href{../appendix/custom.html#binary-typenamesec}{\mathtt{typenamesubsec}} &::=&
\href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}_1(\href{../appendix/custom.html#binary-namemap}{\mathtt{namemap}}) \\
\end{array}\end{split}\]
Field Names
The field name subsection has the id 10.
It consists of an indirect name map assigning field names to field indices grouped by the type indices of their respective structure types.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{field name subsection} & \href{../appendix/custom.html#binary-fieldnamesec}{\mathtt{fieldnamesubsec}} &::=&
\href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}_2(\href{../appendix/custom.html#binary-indirectnamemap}{\mathtt{indirectnamemap}}) \\
\end{array}\end{split}\]
Tag Names
The tag name subsection has the id 11.
It consists of a name map assigning tag names to tag indices.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{tag name subsection} & \href{../appendix/custom.html#binary-tagnamesec}{\mathtt{tagnamesubsec}} &::=&
\href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}_1(\href{../appendix/custom.html#binary-namemap}{\mathtt{namemap}}) \\
\end{array}\end{split}\]
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:
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{name annotation} & \href{../appendix/custom.html#text-nameannot}{\mathtt{nameannot}} &::=&
\def\mathdef124#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef124{(@name}~\href{../text/values.html#text-string}{\mathtt{string}}~\def\mathdef125#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef125{)} \\
\end{array}\end{split}\]
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\mathdef126#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef126{module}\) keyword, or if present, after the following module identifier.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{module name annotation} & \href{../appendix/custom.html#text-modulenameannot}{\mathtt{modulenameannot}} &::=&
\href{../appendix/custom.html#text-nameannot}{\mathtt{nameannot}} \\
\end{array}\end{split}\]
Function Names
A function name annotation must be placed on a function definition or function import,
directly after the \(\def\mathdef127#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef127{func}\) keyword, or if present, after the following function identifier or.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{function name annotation} & \href{../appendix/custom.html#text-funcnameannot}{\mathtt{funcnameannot}} &::=&
\href{../appendix/custom.html#text-nameannot}{\mathtt{nameannot}} \\
\end{array}\end{split}\]
Parameter Names
A parameter name annotation must be placed on a parameter declaration,
directly after the \(\def\mathdef128#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef128{param}\) keyword, or if present, after the following parameter identifier.
It may only be placed on a declaration that declares exactly one parameter.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{parameter name annotation} & \href{../appendix/custom.html#text-paramnameannot}{\mathtt{paramnameannot}} &::=&
\href{../appendix/custom.html#text-nameannot}{\mathtt{nameannot}} \\
\end{array}\end{split}\]
Local Names
A local name annotation must be placed on a local declaration,
directly after the \(\def\mathdef129#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef129{local}\) keyword, or if present, after the following local identifier.
It may only be placed on a declaration that declares exactly one local.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{local name annotation} & \href{../appendix/custom.html#text-localnameannot}{\mathtt{localnameannot}} &::=&
\href{../appendix/custom.html#text-nameannot}{\mathtt{nameannot}} \\
\end{array}\end{split}\]
Type Names
A type name annotation must be placed on a type declaration,
directly after the \(\def\mathdef130#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef130{type}\) keyword, or if present, after the following type identifier.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{type name annotation} & \href{../appendix/custom.html#text-typenameannot}{\mathtt{typenameannot}} &::=&
\href{../appendix/custom.html#text-nameannot}{\mathtt{nameannot}} \\
\end{array}\end{split}\]
Field Names
A field name annotation must be placed on the field of a structure type,
directly after the \(\def\mathdef131#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef131{field}\) keyword, or if present, after the following field identifier.
It may only be placed on a declaration that declares exactly one field.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{field name annotation} & \href{../appendix/custom.html#text-fieldnameannot}{\mathtt{fieldnameannot}} &::=&
\href{../appendix/custom.html#text-nameannot}{\mathtt{nameannot}} \\
\end{array}\end{split}\]
Tag Names
A tag name annotation must be placed on a tag declaration or tag import,
directly after the \(\def\mathdef132#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef132{tag}\) keyword, or if present, after the following tag identifier.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{tag name annotation} & \href{../appendix/custom.html#text-tagnameannot}{\mathtt{tagnameannot}} &::=&
\href{../appendix/custom.html#text-nameannot}{\mathtt{nameannot}} \\
\end{array}\end{split}\]
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\mathdef133#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef133{module}\) keyword, or if present, after the following module identifier.
They must not be nested into other constructs.
\[\begin{split}\begin{array}{llclll}
\def\mathdef83#1{{}}\mathdef83{custom annotation} & \href{../appendix/custom.html#text-customannot}{\mathtt{customannot}} &::=&
\def\mathdef134#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef134{(@custom}~~\href{../text/values.html#text-string}{\mathtt{string}}~~\href{../appendix/custom.html#text-customannot}{\mathtt{customplace}}^?~~\href{../text/modules.html#text-datastring}{\mathtt{datastring}}~~\def\mathdef135#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef135{)} \\
\def\mathdef83#1{{}}\mathdef83{custom placement} & \href{../appendix/custom.html#text-customannot}{\mathtt{customplace}} &::=&
\def\mathdef136#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef136{(}~\def\mathdef137#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef137{before}~~\def\mathdef138#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef138{first}~\def\mathdef139#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef139{)} \\ &&|&
\def\mathdef140#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef140{(}~\def\mathdef141#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef141{before}~~\href{../appendix/custom.html#text-customannot}{\mathtt{sec}}~\def\mathdef142#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef142{)} \\ &&|&
\def\mathdef143#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef143{(}~\def\mathdef144#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef144{after}~~\href{../appendix/custom.html#text-customannot}{\mathtt{sec}}~\def\mathdef145#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef145{)} \\ &&|&
\def\mathdef146#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef146{(}~\def\mathdef147#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef147{after}~~\def\mathdef148#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef148{last}~\def\mathdef149#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef149{)} \\
\def\mathdef83#1{{}}\mathdef83{section} & \href{../appendix/custom.html#text-customannot}{\mathtt{sec}} &::=&
\def\mathdef150#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef150{type} \\ &&|&
\def\mathdef151#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef151{import} \\ &&|&
\def\mathdef152#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef152{func} \\ &&|&
\def\mathdef153#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef153{table} \\ &&|&
\def\mathdef154#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef154{memory} \\ &&|&
\def\mathdef155#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef155{global} \\ &&|&
\def\mathdef156#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef156{export} \\ &&|&
\def\mathdef157#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef157{start} \\ &&|&
\def\mathdef158#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef158{elem} \\ &&|&
\def\mathdef159#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef159{code} \\ &&|&
\def\mathdef160#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef160{data} \\ &&|&
\def\mathdef161#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef161{datacount} \\
\end{array}\end{split}\]
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"
