Skip to content

Latest commit

 

History

History
168 lines (130 loc) · 5.52 KB

ProducersSection.md

File metadata and controls

168 lines (130 loc) · 5.52 KB
Raw

Producers Section

The purpose of the producers section is to provide an optional, highly-structured record of all the distinct tools that were used to produce a given WebAssembly module. A primary purpose of this record is to allow broad analysis of toolchain usage in the wild, which can help inform both wasm producers and consumers.

The producers section is a custom section and thus has no semantic effects and can be stripped at any time. Since the producers section is relatively small, tools are encouraged to emit the section or include themselves in an existing section by default, keeping the producers section even in release builds.

WebAssembly consumers should avoid using the producers section to derive optimization hints. To ensure portable performance, hints should be standardized in a separate custom section, probably in the core spec's Custom Sections appendix.

An additional goal of the producers section is to provide a discrete, but easily-growable list of known tools/languages for each record field. This avoids the skew that otherwise happens with unstructured strings. Unknown names do not invalidate an otherwise-valid producers section. However, wasm consumers may provide less accurate telemetry results for unknown names or even emit diagnostics encouraging the name to be put on the known list.

Since version information is useful, but highly-variable, each field value is accompanied with a version string so that the name can remain stable over time without requiring frequent updates to the known list.

Custom Section

Custom section name field: producers

The producers section may appear only once, and only after the Name section.

The producers section contains a sequence of fields with unique names, where the end of the last field must coincide with the last byte of the producers section:

Field Type Description
field_count varuint32 number of fields that follow
fields field* sequence of field_count field records

where a field is encoded as:

Field Type Description
field_name name name of this field
field_value_count varuint32 number of value strings that follow
field_values versioned-name* sequence of field_value_count name-value pairs

where a versioned-name is encoded as:

Field Type Description
name name name of the language/tool
version name version of the language/tool

with the additional constraint that each field_name in the list must be unique and found in the first column of the following table, and each of a given field_name's field_values's name strings must be unique and found in the second column of the field_name's row.

field_name field_value name strings
language source language list
processed-by individual tool list
sdk SDK list

Known list

The following lists contain all the known names for the fields listed above. If your tool is not on this list and you'd like it to be, please submit a PR.

Source Languages

It is possible for multiple source languages to be present in a single module when the output of multiple compiled languages are statically linked together.

  • wat
  • C
  • C++
  • Rust
  • JavaScript

Individual Tools

It is possible (and common) for multiple tools to be used in the overall pipeline that produces and optimizes a given wasm module.

  • wabt
  • LLVM
  • clang
  • lld
  • Binaryen
  • rustc
  • wasm-bindgen
  • wasm-pack
  • webassemblyjs
  • wasm-snip
  • Javy

SDKs

While an SDK is technically just another tool, the sdk field designates the top-level "thing" that the developer installs and interacts with directly to produce the wasm module.

  • Emscripten
  • Webpack

Text format

The text format for the producers custom section uses annotations proposal extension to the WebAssembly text format. The text format looks like:

(module
  (@producers
    (processed-by "rustc" "1.78.0 (9b00956e5 2024-04-29)")
    (language "Rust" "1.78.0")
  )
)

The (@producers ...) structure must be placed directly within a (module ...) declaration. Within @producers there is a list of parenthesis-delimited fields. The three accepted fields correspond to the three possible field_names above:

  • (language ...)
  • (processed-by ...)
  • (sdk ...)

Each field takes two strings corresponding to the name and version fields of the versioned-name construction in the custom section. For example:

(module
  (@producers
    (language "C" "18.1.2")
    (processed-by "LLVM" "18.1.2")
    (sdk "Emscripten" "3.1.60")
  )
)

The three fields can be specified in any order and any number of times.

(module
  (@producers
    (sdk "Emscripten" "3.1.60")
    (processed-by "LLVM" "18.1.2")
    (language "C" "18.1.2")
    (processed-by "LLVM" "17.1.0")
    (language "Rust" "1.78.0")
    (processed-by "clang" "18.1.2")
  )
)