Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Producers Section to match #93 #100

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 7 additions & 69 deletions ProducersSection.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,12 @@
# 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](https://webassembly.github.io/spec/core/binary/modules.html#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](https://webassembly.github.io/spec/core/appendix/custom.html).

An additional goal of the producers section is to provide a discrete, but
easily-growable [list of known tools/languages](#known-list) 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.
The producers section provides an optional, structured way to record all of the
distinct tools that were used to produce a given WebAssembly module. The
producers section is a [custom section](https://webassembly.github.io/spec/core/binary/modules.html#custom-section)
and thus has no semantic effects. Standard tools like [wabt](https://github.com/webassembly/wabt)'s
`wasm-strip` will remove the producers section, and toolchains which emit the
producers section by default are recommended to have an option to remove it as
well.

## Custom Section

Expand Down Expand Up @@ -71,44 +50,3 @@ the field_name's row.
| `sdk` | [SDK list](#sdks) |

[name-ref]: https://webassembly.github.io/spec/core/binary/values.html#names

## 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`

### 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`

### 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`

## Text format

TODO