alexcrichton opened Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file.- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [ ] Move Rust examples to a top-level
examples
directory- [ ] Move C examples to the top-level
examples
directory too- [ ] Every example has a comment at the top of the file of how to build and run it
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [ ] Wasm files are never checked in for examples
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [ ] Every example is available in both Rust and C
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [ ] All examples are compiled and run on CI, regardless of language, on our three main platforms.
alexcrichton labeled Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file.- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [ ] Move Rust examples to a top-level
examples
directory- [ ] Move C examples to the top-level
examples
directory too- [ ] Every example has a comment at the top of the file of how to build and run it
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [ ] Wasm files are never checked in for examples
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [ ] Every example is available in both Rust and C
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [ ] All examples are compiled and run on CI, regardless of language, on our three main platforms.
tschneidereit labeled Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file.- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [ ] Move Rust examples to a top-level
examples
directory- [ ] Move C examples to the top-level
examples
directory too- [ ] Every example has a comment at the top of the file of how to build and run it
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [ ] Wasm files are never checked in for examples
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [ ] Every example is available in both Rust and C
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [ ] All examples are compiled and run on CI, regardless of language, on our three main platforms.
tschneidereit labeled Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file.- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [ ] Move Rust examples to a top-level
examples
directory- [ ] Move C examples to the top-level
examples
directory too- [ ] Every example has a comment at the top of the file of how to build and run it
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [ ] Wasm files are never checked in for examples
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [ ] Every example is available in both Rust and C
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [ ] All examples are compiled and run on CI, regardless of language, on our three main platforms.
noculture commented on Issue #1272:
I could take a stab at this: "Step-by-step tutorial to create and run hello-world.wasm"
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [ ] Move Rust examples to a top-level
examples
directory- [ ] Move C examples to the top-level
examples
directory too- [ ] Every example has a comment at the top of the file of how to build and run it
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [ ] Wasm files are never checked in for examples
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [ ] Every example is available in both Rust and C
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [ ] All examples are compiled and run on CI, regardless of language, on our three main platforms.
alexcrichton commented on Issue #1272:
I'm working on a number of the examples bullets, mostly around organizing them and bringing C on par with Rust. Also CI!
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [ ] Move Rust examples to a top-level
examples
directory - @alexcrichton- [ ] Move C examples to the top-level
examples
directory too - @alexcrichton- [ ] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [ ] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [ ] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [ ] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
sunfishcode commented on Issue #1272:
I'll write some content for the Sandboxing section.
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [ ] Move Rust examples to a top-level
examples
directory - @alexcrichton- [ ] Move C examples to the top-level
examples
directory too - @alexcrichton- [ ] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [ ] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [ ] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [ ] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [ ] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [ ] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [ ] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [ ] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [ ] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [ ] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [ ] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [ ] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [ ] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [ ] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [ ] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [ ] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [ ] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [ ] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [ ] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [ ] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [x] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [x] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [ ] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [x] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [x] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [x] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [x] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
jjsullivan5196 commented on Issue #1272:
I can work on getting the python examples illustrated in the documentation. I think the demo video on the wasmtime home page is pretty comprehensive, so I'll probably just add some more details for project setup with things like pipenv and the like https://youtu.be/Qn_4F3foB3Q
jjsullivan5196 edited a comment on Issue #1272:
I can work on getting the python examples illustrated in the documentation. I think the demo video on the wasmtime home page is pretty comprehensive, so I'll probably just add some more details for project setup with things like pipenv and the like https://youtu.be/Qn_4F3foB3Q @alexcrichton do you think this is a good approach?
jjsullivan5196 edited a comment on Issue #1272:
I can work on getting the python examples illustrated in the documentation. I think the demo video on the wasmtime home page is pretty comprehensive, so I'll probably just add some more details for project setup with pipenv and the like https://youtu.be/Qn_4F3foB3Q @alexcrichton do you think this is a good approach?
jjsullivan5196 edited a comment on Issue #1272:
I can work on getting the python examples illustrated in the documentation. I think the demo video on the wasmtime home page is pretty comprehensive, so I'll probably just add some more details for project setup with pipenv and the like https://youtu.be/Qn_4F3foB3Q @alexcrichton do you think this is a good approach?
Also just saw #677, do you think I can still document the python support as of v0.12.0, or should I wait until interface types are more stable? The issue makes it seem like the interface shouldn't change much for module users.
alexcrichton commented on Issue #1272:
@jjsullivan5196 sounds great to me! I do think we should still at least document what we have which should work well for integers and such, but yeah the exact video won't work any more because strings are no longer supported.
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [x] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python - @jjsullivan5196
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [x] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [x] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
humancalico commented on Issue #1272:
@alexcrichton I'll write the markdown parser for the book
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [x] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python - @jjsullivan5196
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example - @humancalico
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [x] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [ ] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [x] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [x] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python - @jjsullivan5196
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example - @humancalico
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [ ] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [x] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [x] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [x] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
sunfishcode edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [x] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [ ] Documenation of using wasm from Python - @jjsullivan5196
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example - @humancalico
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [x] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [x] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [x] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [x] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [x] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [x] Documenation of using wasm from Python - @jjsullivan5196
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example - @humancalico
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [x] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [x] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [x] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [x] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [x] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [x] Documenation of using wasm from Python - @jjsullivan5196
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example - @humancalico
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [x] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [x] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [x] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [x] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [x] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [x] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [x] Documenation of using wasm from Python - @jjsullivan5196
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example - @humancalico
- [ ] Embedding wasmtime overview
- [ ] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [x] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [x] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [x] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [x] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
Hyperion101010 commented on Issue #1272:
Hi there Shivam here. I can try on working "Documentation of using wasm from Rust" @alexcrichton .
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [x] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [x] Documenation of using wasm from Python - @jjsullivan5196
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example - @humancalico
- [ ] Embedding wasmtime overview
- [x] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [ ] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [x] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [x] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [x] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [x] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
alexcrichton edited Issue #1272:
I'd like to use this issue as a tracking issue for filling out gaps in
wasmtime
's introductory documentation. This includes our book (rendered), API documentation (rendered), and examples. (or anything else others can think of as well!)Below I'm gonna fill out a bunch of checkmarks and checkboxes for what is currently missing at this time. If you'd like to help in and document things, please feel free to do so! If you leave a comment on this issue along with what you'd like to help fill in, we'll edit your name into the description here to know that it's claimed. Any and all help here is greatly appreciated!
Book Documentation
As a precursor I'll say that this is organized largely page-by-page in the book. The current organization of the book was an initial proposal from awhile ago and thinking back on it some of it may be a little redundant. Please feel free to also discuss the layout of the book and what documentation would best go where!
- [x] Step-by-step tutorial to create and run hello-world.wasm. This is intended to be a gentle introduction to running code with wasmtime, originating from nothing and ending using the
wasmtime
CLI to execute a Rust-generated WebAssembly file - @noculture- [ ] List of example programs compiled to WebAssembly. We'll want to include some listings of a few "hello world" wasm modules as well as some more complicated ones like Rust projects with Cargo dependencies (e.g. a markdown parser)
- [x] Documenation of using wasm from Python - @jjsullivan5196
- [ ] Documentation of using wasm from .NET
- [ ] Documentation of using wasm from Rust (not necessarily detailed embedder docs, but more of how you might use wasmtime at a high level to plug into a larger application)
- [ ] Documentation of using wasm from bash (aka examples of using the CLI)
- [ ] Writing WebAssembly from C/C++
- [ ] Writing WebAssembly, markdown example - @humancalico
- [ ] Embedding wasmtime overview
- [x] Embedding wasmtime in Rust - currently has docs but feels a bit light on content
- [x] Embedding wasmtime in C/C++
- [ ] Embedding wasmtime in .NET - probably want a page on this?
- [ ] What stability means in wasmtime - probably want to talk about what our version scheme is, what's stable, what's not, etc.
- [ ] Release process - documenting a release cadence, when releases happen, policies for releases, where releases are announced, etc.
- [ ] Platform support - currently contains a lot of introductory documentation, feels pretty light though and like it could be better tied together.
- [ ] Security policy
- [ ] Disclosure policy
- [x] Sandboxing - @sunfishcode
- [ ] Governance
API Documentation
- [ ] The crate documentation feels lacking and could use a broad example to introduce the crate.
- [x] The
Module
type should have at least one example somewhere.- [ ] The
Instance
type should have at least one example.- [ ] The
Store
type needs more documentation about what it is, although this is somewhat up for debate in other issues as well.- [x] The
Memory
type needs examples of safe usage, and double-checks on wording about unsafe usage.- [ ] The
Func
type could use an example on theget
family of methods.- [ ] Types which correspond to the wasm specification should link there where possible.
Examples
I think we want an overhaul of how our examples work. Here's my proposal for what we need to do:
- [x] Move Rust examples to a top-level
examples
directory - @alexcrichton- [x] Move C examples to the top-level
examples
directory too - @alexcrichton- [x] Every example has a comment at the top of the file of how to build and run it - @alexcrichton
- Rust is typically
cargo run --example foo
- C is
gcc examples/foo.c -I crates/c-api/include -o foo && ./foo
(ish)- [x] Wasm files are never checked in for examples - @alexcrichton
- Either wasm is written inline as a
*.wat
string- Or example is structured as
examples/name/main.rs
with a correspondingexamples/name/wasm/Cargo.toml
which is a Rust project compiled to wasm. (orexamples/name/wasm.c
if we want to show off a C-compiled wasm example)- [x] Every example is available in both Rust and C - @alexcrichton
- For
examples/foo.rs
we have a correspondingexamples/foo.c
- For
examples/foo/main.rs
we have a correspondingexamples/foo/main.c
- [ ] Example showing how to link in the WASI functions
- [ ] Example of reading a string from a wasm module
- [ ] Example of a string processor, for example a markdown renderer
- [x] All examples are compiled and run on CI, regardless of language, on our three main platforms. - @alexcrichton
Last updated: Dec 23 2024 at 13:07 UTC