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

Bring some of Wasmtime's documentation more up-to-date #6994

Merged
merged 7 commits into from
Sep 11, 2023

Conversation

alexcrichton
Copy link
Member

Wasmtime has a fair bit of docs which are quite dated at this point or also somewhat duplicated. Additionally Wasmtime has a number of sections of "more coming soon!" where "soon" hasn't happened in a few years. I've gone through some sections here and tried to modernize docs a bit, and the high-level changes are:

  • Documentation about writing wasm is removed.
  • Wasm/WASI proposals are folded into tier documentation.
  • The tier documentation now additionally documents unsupported features.

This commit removes the tutorial and "Writing WebAssembly" documentation
sections from Wasmtime's documentation. These sections are quite dated
at this point (they still recommend `cargo wasi`!) and haven't been
updated much since their inception, especially in the arena of
components. Today it seems best to leave this sort of documentation to
[other resources] which are more tailored towards documentation of
writing wasm.

[other resources]: https://component-model.bytecodealliance.org/
Like the previous commit this is quite dated and recommends
effectively-deprecated tooling and doesn't take into account components.
This was already a bit duplicated so consolidate into one location.
Additionally add some proposals that weren't previously documented and
move some around based on their implementation status.
In an effort to head off questions about platform support I figure it
might be a good idea to start documenting what's not supported at this
time. This is intended to mirror the current state, not future, of
Wasmtime. In other words this should answer the question of "Does
Wasmtime support X?" as opposed to "Does Wasmtime want to support X?"
since we want to eventually support all of these features in the limit.
Similar to the previous commit but for WASI proposals.
@alexcrichton alexcrichton requested a review from a team as a code owner September 11, 2023 16:10
@alexcrichton alexcrichton requested review from fitzgen and removed request for a team September 11, 2023 16:10
@alexcrichton alexcrichton added this pull request to the merge queue Sep 11, 2023
Merged via the queue into bytecodealliance:main with commit 0ee6641 Sep 11, 2023
18 checks passed
@alexcrichton alexcrichton deleted the update-docs branch September 11, 2023 17:36
alexcrichton added a commit that referenced this pull request Sep 12, 2023
* Remove tutorial/wasm-writing documentation

This commit removes the tutorial and "Writing WebAssembly" documentation
sections from Wasmtime's documentation. These sections are quite dated
at this point (they still recommend `cargo wasi`!) and haven't been
updated much since their inception, especially in the arena of
components. Today it seems best to leave this sort of documentation to
[other resources] which are more tailored towards documentation of
writing wasm.

[other resources]: https://component-model.bytecodealliance.org/

* Remove markdown example from docs

Like the previous commit this is quite dated and recommends
effectively-deprecated tooling and doesn't take into account components.

* Update our intro docs a bit

* Link security blog post from docs

* Fold docs of wasm proposals into tier docs

This was already a bit duplicated so consolidate into one location.
Additionally add some proposals that weren't previously documented and
move some around based on their implementation status.

* Document unsupported features

In an effort to head off questions about platform support I figure it
might be a good idea to start documenting what's not supported at this
time. This is intended to mirror the current state, not future, of
Wasmtime. In other words this should answer the question of "Does
Wasmtime support X?" as opposed to "Does Wasmtime want to support X?"
since we want to eventually support all of these features in the limit.

* Fold WASI docs into tier docs

Similar to the previous commit but for WASI proposals.
eduardomourar pushed a commit to eduardomourar/wasmtime that referenced this pull request Sep 13, 2023
…nce#6994)

* Remove tutorial/wasm-writing documentation

This commit removes the tutorial and "Writing WebAssembly" documentation
sections from Wasmtime's documentation. These sections are quite dated
at this point (they still recommend `cargo wasi`!) and haven't been
updated much since their inception, especially in the arena of
components. Today it seems best to leave this sort of documentation to
[other resources] which are more tailored towards documentation of
writing wasm.

[other resources]: https://component-model.bytecodealliance.org/

* Remove markdown example from docs

Like the previous commit this is quite dated and recommends
effectively-deprecated tooling and doesn't take into account components.

* Update our intro docs a bit

* Link security blog post from docs

* Fold docs of wasm proposals into tier docs

This was already a bit duplicated so consolidate into one location.
Additionally add some proposals that weren't previously documented and
move some around based on their implementation status.

* Document unsupported features

In an effort to head off questions about platform support I figure it
might be a good idea to start documenting what's not supported at this
time. This is intended to mirror the current state, not future, of
Wasmtime. In other words this should answer the question of "Does
Wasmtime support X?" as opposed to "Does Wasmtime want to support X?"
since we want to eventually support all of these features in the limit.

* Fold WASI docs into tier docs

Similar to the previous commit but for WASI proposals.
alexcrichton added a commit to alexcrichton/wasmtime that referenced this pull request Apr 15, 2024
The documentation referring to this example was removed in bytecodealliance#6994 and
that forgot to remove this as well. This example is building without a
lock file which is causing issues in bytecodealliance#8368.
alexcrichton added a commit to alexcrichton/wasmtime that referenced this pull request Apr 15, 2024
The documentation referring to this example was removed in bytecodealliance#6994 and
that forgot to remove this as well. This example is building without a
lock file which is causing issues in bytecodealliance#8368.
alexcrichton added a commit to alexcrichton/wasmtime that referenced this pull request Apr 15, 2024
…xample (bytecodealliance#8369)

* Use `--locked` on all `cargo install` in CI

Prevents any updates to rustc or crates from accidentally causing issues
by ensuring that the same set of deps is used over time.

* Remove rust/WASI markdown parser example

The documentation referring to this example was removed in bytecodealliance#6994 and
that forgot to remove this as well. This example is building without a
lock file which is causing issues in bytecodealliance#8368.
github-merge-queue bot pushed a commit that referenced this pull request Apr 15, 2024
…xample (#8369)

* Use `--locked` on all `cargo install` in CI

Prevents any updates to rustc or crates from accidentally causing issues
by ensuring that the same set of deps is used over time.

* Remove rust/WASI markdown parser example

The documentation referring to this example was removed in #6994 and
that forgot to remove this as well. This example is building without a
lock file which is causing issues in #8368.
fitzgen added a commit that referenced this pull request Apr 15, 2024
* c-api: Better differentiate between `wasm.h` and `wasmtime.h` APIs (#8344)

This renames some types and adds some type aliases to help us better distinguish
between `wasm.h` APIs and `wasmtime.h` APIs, primarily for `Store`-related
types. In general, `WasmFoo` is related to `wasm.h` and `WasmtimeFoo` is related
to `wasmtime.h`.

* `StoreRef` -> `WasmStoreRef`
* Introduce the `WasmStore[Data]` and `WasmStoreContext[Mut]` aliases
* `StoreData` -> `WasmtimeStoreData`
* `CStoreContext[Mut]` -> `WasmtimeStoreContext[Mut]`
* Introduce the `Wasmtime{Store,Caller}` aliases

* `wasmtime-c-api`: Improve non-support of GC references in `wasm.h` APIs (#8345)

* c-api: Better differentiate between `wasm.h` and `wasmtime.h` APIs

This renames some types and adds some type aliases to help us better distinguish
between `wasm.h` APIs and `wasmtime.h` APIs, primarily for `Store`-related
types. In general, `WasmFoo` is related to `wasm.h` and `WasmtimeFoo` is related
to `wasmtime.h`.

* `StoreRef` -> `WasmStoreRef`
* Introduce the `WasmStore[Data]` and `WasmStoreContext[Mut]` aliases
* `StoreData` -> `WasmtimeStoreData`
* `CStoreContext[Mut]` -> `WasmtimeStoreContext[Mut]`
* Introduce the `Wasmtime{Store,Caller}` aliases

* c-api: Improve non-support of GC references in `wasm.h` APIs

A couple small tweaks: error message improvements, exhaustive matching, etc...

* Fix running wasi-common tests on CI (#8353)

* Fix running wasi-common tests on CI

Turns out we haven't been running wasi-common tests for some time in CI
and they've started failing. Force enable the test at all times and then
fix the test failures. The test failures here were introduced in #8277
and weren't caught due to the test not running and the fix was to relax
the implementation of `fd_pread` to avoid taking multiple mutable
borrows.

* Fix CI

* Update release notes for 20.0.0 (#8358)

A busy release!

* Enable the gc feature by default in the c-api (#8356)

Match the Wasmtime crate in this respect

* wasmtime-c-api: Add support for GC references in `wasmtime.h` APIs (#8346)

Restores support for `externref` in `wasmtime_val_t`, methods for manipulating
them and getting their wrapped host data, and examples/tests for these things.

Additionally adds support for `anyref` in `wasmtime_val_t`, clone/delete methods
similar to those for `externref`, and a few `i31ref`-specific methods. Also adds
C and Rust example / test for working with `anyref`.

* Fix calculation of gc refs in functions (#8355)

* Fix calculation of gc refs in functions

In addition to excluding i31 also exclude funcrefs.

* Review comments

* Remove `wasi_config_preopen_socket` from C header (#8364)

This was removed in #8066

* Tidy up some headers related to shared memory (#8366)

* Tidy up some headers related to shared memory

* Don't declare an anonymous `struct wasmtime_sharedmemory`, instead
  `#include` the actual definition.
* Fix an issue where a header in `sharedmemory.h` referred to a type in
  `extern.h` which wasn't `#include`'d. This function,
  `wasmtime_sharedmemory_into_extern`, additionally isn't necessary as
  it's no different than manually constructing it. Fix this by removing
  this function.

* Run clang-format

* c-api: Fix alignment of `wasmtime_val_*` (#8363)

* c-api: Fix alignment of `wasmtime_val_*`

This commit fixes an issue where `wasmtime_val_raw_t` had an incorrect
alignment. In Rust `ValRaw` contains a `u128` which has an alignment of
16 but in C the representation had a smaller alignment meaning that the
alignment of the two structures was different. This was seen to cause
alignment faults when structure were passed from C++ to Rust, for
example.

This commit changes the Rust representation of `ValRaw`'s `v128` field
to do the same as C which is to use `[u8; 16]`. This avoids the need to
raise the alignment in C which appears to be nontrivial. Cranelift is
appropriately adjusted to understand that loads/stores from `ValRaw` are
no longer aligned. Technically this only applies to the `v128` field but
it's not too bad to apply it to the other fields as well.

* Try alternate syntax for alignof

* Use `--locked` on all `cargo install` in CI, also remove non-locked example (#8369)

* Use `--locked` on all `cargo install` in CI

Prevents any updates to rustc or crates from accidentally causing issues
by ensuring that the same set of deps is used over time.

* Remove rust/WASI markdown parser example

The documentation referring to this example was removed in #6994 and
that forgot to remove this as well. This example is building without a
lock file which is causing issues in #8368.

---------

Co-authored-by: Nick Fitzgerald <fitzgen@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants