Merge branch 'main' into qt-training-material

ferrous-systems · Nov 17, 2023 · d945b66 · d945b66
2 parents d4e37d1 + f1a715e
commit d945b66
Show file tree

Hide file tree

Showing 60 changed files with 342 additions and 3,359 deletions.
diff --git a/book/src/README.md b/book/src/README.md
@@ -8,11 +8,6 @@ It is split into 3 parts:
 
 An installation guide for all tooling used throughout this book.
 
-## Part 2: [Background](what-is-webassembly.md)
-
-A bit of common knowledge & history about WebAssembly and Rust,
-as well as notable use cases.
-
-## Part 3: [Tutorial](./tutorial/index.md)
+## Part 2: [Tutorial](./tutorial/index.md)
 
 A hands-on tutorial writing Rust and compiling it in 3 variations: as a command-line app, as a library and as a small Qt app using the library using cxx-qt.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -6,30 +6,23 @@
   - [Setup](./setup.md)
   - [Tooling check](./tooling-check.md)
 
-# Background
-
-- [What is WebAssembly?](./what-is-webassembly.md)
-  - [Hello World](./wasm-hello-world.md)
-  - [Rust & Wasm](./rust-and-wasm.md)
-- [Use cases on the web](./on-the-web/usecases.md)
-  - [WASM & JavaScript](./on-the-web/wasm-and-js.md)
-- [Use cases everywhere else](./on-the-server/usecases.md)
-  - [WASI](./on-the-server/wasi.md)
-  - [Fastly's Compute@Edge](./on-the-server/compute-at-edge.md)
-
 # Tutorial
 
 - [Idea](./tutorial/index.md)
 - [CLI](./tutorial/cli.md)
   - [Hello World](./tutorial/cli/hello-world.md)
-  - [Building and running with wasmtime](./tutorial/cli/building-cli.md)
-  - [Image filter application](./tutorial/cli/image-filters.md)
+  - [Image filter CLI application](./tutorial/cli/image-filters.md)
   - [Final application](./tutorial/cli/final-code.md)
+- [Implementing a library](./tutorial/library.md)
+  - [Recreate the project as a workspace](./tutorial/library/recreate-as-workspace.md)
+  - [Creating the library](./tutorial/library/create-library.md)
+  - [Using the library in your CLI binary](./tutorial/library/cli-with-library.md)
 - [Qt GUI](./tutorial/qt-gui/index.md)
   - [Setting up the build system](./tutorial/qt-gui/build-setup.md)
   - [Creating the QML GUI](./tutorial/qt-gui/creating-the-gui.md)
   - [QQuickPaintedItem in Rust](./tutorial/qt-gui/qquickpainteditem.md)
   - [Adding behavior in Rust](./tutorial/qt-gui/rust-implementation.md)
+
 ---
 
 - [References](./references.md)
diff --git a/book/src/on-the-server/compute-at-edge.md b/book/src/on-the-server/compute-at-edge.md
diff --git a/book/src/on-the-server/serverless.md b/book/src/on-the-server/serverless.md
diff --git a/book/src/on-the-server/usecases.md b/book/src/on-the-server/usecases.md
diff --git a/book/src/on-the-server/wasi.md b/book/src/on-the-server/wasi.md
diff --git a/book/src/on-the-web/usecases.md b/book/src/on-the-web/usecases.md
diff --git a/book/src/on-the-web/wasm-and-js.md b/book/src/on-the-web/wasm-and-js.md
diff --git a/book/src/references.md b/book/src/references.md
@@ -1,5 +1,7 @@
 # References
 
+TODO: Redo References
+
 * [The official WebAssembly website](https://webassembly.org/)
 * [The Rust Wasm Book](https://rustwasm.github.io/docs/book/)
 * [wasm-bindgen documentation](https://rustwasm.github.io/docs/wasm-bindgen)

diff --git a/book/src/rust-and-wasm.md b/book/src/rust-and-wasm.md
diff --git a/book/src/tutorial/cli.md b/book/src/tutorial/cli.md
@@ -2,10 +2,11 @@
 
 In this tutorial you'll get familiar with:
 
-* Building Rust code for the `wasm32-wasi` target
-* Running applications on the command-line using `wasmtime`
-* Re-using existing crates in a WASM application
-* `wasmtime`'s capability-based system
+* Building Rust code for your local target
+* Running applications on the command-line
+* Parsing command line parameters by hand
+* Re-using existing crates in your application
+* Rust type systems basics
 
 We start with a command-line tool that takes an image and a filter name as input.
 It applies the given filter to the image and produces an `output.png`.
diff --git a/book/src/tutorial/cli/building-cli.md b/book/src/tutorial/cli/building-cli.md
diff --git a/book/src/tutorial/cli/final-code.md b/book/src/tutorial/cli/final-code.md
@@ -20,19 +20,29 @@ To recap your final code should look something like this:
 You can build your code like this:
 
 ```
-cargo build --target wasm32-wasi
+cargo build
 ```
 
-And run it with `wasmtime`:
+And run it using cargo:
 
 ```
-wasmtime --dir . target/wasm32-wasi/debug/rustagram.wasm skyline.jpg 1977
+cargo run
+```
+
+For an optimized build use:
+
+```
+cargo build --release
+```
+
+```
+cargo run --release
 ```
 
 ---
 
 Some ideas on what to do next:
 
 * Run the application natively: `cargo run`. Any complications or differences?
-* Inspect the built wasm module using `wasm2wat`. Can you spot the parts of the code that you've written? Can you find the names of all available filters?
-* Try some other crate you know. Does it work as-is on WebAssembly/with Wasi?
+* Heard of WebAssembly? You can actually run this in WebAssembly - see our [WASM Training](https://github.com/ferrous-systems/wasm-training-2022)
+* Try a full command line parser crate - see [blessed.rs for suggestions](https://blessed.rs/crates#section-cli-tools-subsection-argument-parsing)
diff --git a/book/src/tutorial/cli/hello-world.md b/book/src/tutorial/cli/hello-world.md
@@ -15,4 +15,4 @@ fn main() {
 }
 ```
 
-Next, [read how to build and run the application](building-cli.md).
+Next, [start integrating image filters](image-filters.md).
diff --git a/book/src/tutorial/cli/image-filters.md b/book/src/tutorial/cli/image-filters.md
@@ -77,40 +77,21 @@ Try it for yourself!
 Expected output when you don't pass any arguments:
 
 ```console
-$ wasmtime target/wasm32-wasi/debug/rustagram.wasm
-thread 'main' panicked at 'INPUT required', src/main.rs:7:29
+$ cargo run
+thread 'main' panicked at src\main.rs:5:29:
+INPUT required
 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
-Error: failed to run main module `target/wasm32-wasi/debug/rustagram.wasm`
-
-Caused by:
-    0: failed to invoke command default
-[...]
 ```
 
 Expected output when you pass a file path and a filter name:
 
 ```console
-$ wasmtime target/wasm32-wasi/debug/rustagram.wasm kongelige-slott.jpg 1977
-thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: IoError(Custom { kind: Uncategorized, error: "failed to find a pre-opened file descriptor through which \"kongelige-slott.jpg\" could be opened" })', src/main.rs:12:34
+$ cargo run -- kongelige-slott.jpg 1977
+    Finished dev [unoptimized + debuginfo] target(s) in 0.09s
+     Running `target\debug\rustagram.exe kongelige-slott.jpg 1977`
+thread 'main' panicked at src\main.rs:10:34:
+called `Result::unwrap()` on an `Err` value: IoError(Os { code: 2, kind: NotFound, message: "The system cannot find the file specified." })
 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
-Error: failed to run main module `target/wasm32-wasi/debug/rustagram.wasm`
-
-Caused by:
-    0: failed to invoke command default
-[...]
-```
-
----
-
-What did just happen?
-
-`wasmtime` ran your code up until it tried to read the image from disk.
-By default `wasmtime` blocks all filesystem access.
-You need to explicitly give permission to specific directories in order to be able to read and writes files within.
-
-```console
-$ wasmtime --dir . target/wasm32-wasi/debug/rustagram.wasm kongelige-slott.jpg 1977
-$
 ```
 
-This should now have created `output.jpg`.
+TODO: document positive case
-Original file line number
+Diff line change
@@ Expand Up / @@ -15,4 +15,4 @@ fn main() { @@
     }
     ```
-    Next, [read how to build and run the application](building-cli.md).
+    Next, [start integrating image filters](image-filters.md).