Custom Sections

This appendix defines dedicated custom sections for WebAssembly’s binary format. Such sections do not contribute to, or otherwise affect, the WebAssembly semantics, and like any custom section they 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.

Currently, only one dedicated custom section is defined, the name section.

Name Section

The name section is a custom sections whose name string is itself \(\def\mathdef115#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef115{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}{\def\mathdef64#1{{\mathit{u}#1}}\mathdef64{\mathit{32}}}\) size of the contents, in bytes,
  • the actual contents, whose structure is depended on the subsection id.
\[\begin{split}\begin{array}{llcll} \def\mathdef58#1{{}}\mathdef58{name section} & \href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesec}} &::=& \href{../binary/modules.html#binary-module}{\mathtt{section}}_0(\href{../appendix/custom.html#binary-namesubsection}{\mathtt{namedata}}) \\ \def\mathdef58#1{{}}\mathdef58{name data} & \href{../appendix/custom.html#binary-namesubsection}{\mathtt{namedata}} &::=& n{:}\href{../binary/values.html#binary-name}{\mathtt{name}}~~\href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}^\ast & (\mathrel{\mbox{if}} n = \def\mathdef116#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef116{name}) \\ \def\mathdef58#1{{}}\mathdef58{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\mathdef84#1{{\mathtt{u}#1}}\mathdef84{\mathtt{32}}}~~\mathtt{B} & (\mathrel{\mbox{if}} \mathit{size} = ||\mathtt{B}||) \\ \end{array}\end{split}\]

The following subsection ids are used:

Id Subsection
0 module name
1 function names
2 local names

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\mathdef58#1{{}}\mathdef58{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\mathdef58#1{{}}\mathdef58{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\mathdef58#1{{}}\mathdef58{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\mathdef58#1{{}}\mathdef58{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\mathdef58#1{{}}\mathdef58{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\mathdef58#1{{}}\mathdef58{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\mathdef58#1{{}}\mathdef58{function name subsection} & \href{../appendix/custom.html#binary-funcnamesec}{\mathtt{funcnamesubsec}} &::=& \href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}_2(\href{../appendix/custom.html#binary-indirectnamemap}{\mathtt{indirectnamemap}}) \\ \end{array}\end{split}\]