Stream: git-wasmtime

Topic: wasmtime / Issue #1272 Filling out missing Introductory D...

Wasmtime GitHub notifications bot (Mar 10 2020 at 18:34):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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.

Wasmtime GitHub notifications bot (Mar 10 2020 at 18:34):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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.

Wasmtime GitHub notifications bot (Mar 10 2020 at 20:38):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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.

Wasmtime GitHub notifications bot (Mar 10 2020 at 20:38):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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.

Wasmtime GitHub notifications bot (Mar 10 2020 at 20:50):

noculture commented on Issue #1272:

I could take a stab at this: "Step-by-step tutorial to create and run hello-world.wasm"

Wasmtime GitHub notifications bot (Mar 10 2020 at 21:21):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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.

Wasmtime GitHub notifications bot (Mar 10 2020 at 23:14):

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!

Wasmtime GitHub notifications bot (Mar 10 2020 at 23:15):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 11 2020 at 00:10):

sunfishcode commented on Issue #1272:

I'll write some content for the Sandboxing section.

Wasmtime GitHub notifications bot (Mar 11 2020 at 13:01):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 11 2020 at 20:37):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 11 2020 at 20:37):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 11 2020 at 20:37):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 11 2020 at 20:37):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 11 2020 at 20:37):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 11 2020 at 20:37):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 12 2020 at 15:49):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 12 2020 at 21:41):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 13 2020 at 01:52):

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

Wasmtime GitHub notifications bot (Mar 13 2020 at 01:53):

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?

Wasmtime GitHub notifications bot (Mar 13 2020 at 02:00):

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?

Wasmtime GitHub notifications bot (Mar 13 2020 at 02:41):

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.

Wasmtime GitHub notifications bot (Mar 13 2020 at 16:23):

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.

Wasmtime GitHub notifications bot (Mar 13 2020 at 16:23):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 15 2020 at 14:37):

humancalico commented on Issue #1272:

@alexcrichton I'll write the markdown parser for the book

Wasmtime GitHub notifications bot (Mar 17 2020 at 14:27):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 18 2020 at 19:40):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 21 2020 at 04:25):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 24 2020 at 14:44):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 24 2020 at 14:44):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Mar 24 2020 at 14:44):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Apr 17 2020 at 08:33):

Hyperion101010 commented on Issue #1272:

Hi there Shivam here. I can try on working "Documentation of using wasm from Rust" @alexcrichton .

Wasmtime GitHub notifications bot (Apr 17 2020 at 20:47):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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

Wasmtime GitHub notifications bot (Apr 17 2020 at 20:48):

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 the get 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 corresponding examples/name/wasm/Cargo.toml which is a Rust project compiled to wasm. (or examples/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 corresponding examples/foo.c
  • For examples/foo/main.rs we have a corresponding examples/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: Oct 23 2024 at 20:03 UTC