Skip to content

Commit 4f6e921

Browse files
thewtexthewtex
committed
docs: provide Podman installation instructions
And recommend over docker, especially on Windows.
1 parent febf2de commit 4f6e921

File tree

3 files changed

+588
-588
lines changed

3 files changed

+588
-588
lines changed

‎docs/cxx/tutorial/debugging.md‎

Lines changed: 174 additions & 174 deletions
Original file line numberDiff line numberDiff line change
@@ -1,174 +1,174 @@
1-
# Debugging WebAssembly
2-
3-
Effective debugging results in effective programming. **itk-wasm** makes effective debugging of WebAssembly possible.
4-
5-
This example walks through the different techniques that can be used with itk-wasm to debug WebAssembly during development.
6-
7-
We will debug the following C++ code:
8-
9-
```cpp
10-
#include <iostream>
11-
12-
int main() {
13-
std::cout << "Hello debugger world!" << std::endl;
14-
15-
const char * wasmDetails = "are no longer hidden";
16-
17-
const int a = 1;
18-
const int b = 2;
19-
const auto c = a + b;
20-
21-
// Simulate a crash.
22-
abort();
23-
return 0;
24-
}
25-
```
26-
27-
[The example](https://github.com/InsightSoftwareConsortium/itk-wasm/tree/main/examples/debugging) provides npm scripts as a convenient way to execute debugging commands that you may also invoke directly in a command line shell.
28-
29-
To run these examples, first [install and test](./hello_world) Docker and Node/NPM. Then, install the package dependencies and run the example commands.
30-
31-
```
32-
cd itk-wasm/examples/Debugging/
33-
npm install
34-
npm run <name>
35-
```
36-
37-
where `<name>` is the npm script. Available names can be found by calling `npm run` without any arguments.
38-
39-
## Native
40-
41-
The CMake-based itk-wasm build system tooling enables the same C++ build system configuration and code to be reused when building a native system binary or a WebAssembly binary. As a result, native binary debugging tools, such as [GDB](https://sourceware.org/gdb/), [LLDB](https://lldb.llvm.org/), or the [Visual Studio debugger](https://docs.microsoft.com/en-us/visualstudio/debugger/?view=vs-2022).
42-
43-
We can build the project's standard CMake build configuration,
44-
45-
```cmake
46-
cmake_minimum_required(VERSION 3.10)
47-
project(DebuggingWebAssemblyExample)
48-
49-
add_executable(DebugMe DebugMe.cxx)
50-
```
51-
52-
with standard CMake commands,
53-
54-
![Native build](/_static/tutorial/debugging/native-build.png)
55-
56-
The native binary can then be debugged in the standard way. For example, with `gdb` on Linux:
57-
58-
![Native debug Linux](/_static/tutorial/debugging/native-debug-linux.png)
59-
60-
## WASI
61-
62-
The most direct way to debug WebAssembly is through the [WebAssembly System Interface (WASI)](https://wasi.dev/). In itk-wasm we can build to WASI with the [WASI SDK](https://github.com/WebAssembly/wasi-sdk) by specifying the `itkwasm/wasi` toolchain image. A backtrace can quickly be obtained with the `itk-wasm` CLI. Or, a fully fledged debugger session can be started with LLDB.
63-
64-
First, build to WASI WebAssembly with debugging symbols available:
65-
66-
![WASI debug build](/_static/tutorial/debugging/wasi-build-debug.png)
67-
68-
Then, the `itk-wasm` CLI can conveniently run the Wasm binary with the included WASI runtime:
69-
70-
![Run WASI debug](/_static/tutorial/debugging/run-wasi-debug.png)
71-
72-
We can see that `abort` is called in the `main` function at line 13 in `DebugMe.cxx`.
73-
74-
A full debugging session is also possible after [LLDB](https://lldb.llvm.org/) >= 13 and [Wasmtime](https://wasmtime.dev/) are installed.
75-
76-
![LLDB WASI debug](/_static/tutorial/debugging/lldb-wasi-debug.png)
77-
78-
**Note:** when calling `wasmtime` directly and passing local files into a pipeline, `--dir` arguments must be set. This gives `wasmtime` permission to access the directories containing the files. This is required due to WASI's [capability-based security](https://en.wikipedia.org/wiki/Capability-based_security) model. For example, if a file path starts with `./`, then add `--dir ./` arguments to the `wasmtime` invocation. `--dir` can be specified multiple times.
79-
80-
## Node.js
81-
82-
When debugging WebAssembly built with the itk-wasm Emscripten toolchain, set the `CMAKE_BUILD_TYPE` to `Debug` as is required to debug native builds.
83-
84-
As with native builds, this builds debugging symbols, the human-readable names of functions, variables, etc., into the binary. This also adds support for C++ exceptions and retrieving the string name associated with exceptions. Without this itk-wasm instrumentation, a C++ exception will through an error with an opaque integer value. And, Emscripten JavaScript WebAssembly bindings will not be minified, which facilitates debugging.
85-
86-
When built with the default `Release` build type:
87-
88-
![Emscripten build Release](/_static/tutorial/debugging/emscripten-build-release.png)
89-
90-
the JavaScript support code is minified, and difficult to debug:
91-
92-
![Run Node Release](/_static/tutorial/debugging/run-node-release.png)
93-
94-
However, when built with the `Debug` build type:
95-
96-
![Emscripten build Debug](/_static/tutorial/debugging/emscripten-build-debug.png)
97-
98-
a useful backtrace can be obtained:
99-
100-
![Run Node Debug](/_static/tutorial/debugging/run-node-debug.png)
101-
102-
In order to run a debugger with Node, add the `--inspect-brk` flag when invoking `node`:
103-
104-
![Node inspect](/_static/tutorial/debugging/node-inspect.png)
105-
106-
This will pause execution on start a debugging remote interface. To connect to the remote interface with a Chromium browser, visit `chrome://inspect` and click the *inspect* link on the corresponding *Remote Target*:
107-
108-
![Node inspect Remote Target](/_static/tutorial/debugging/node-inspect-remote-target.png)
109-
110-
This will open the Chrome Dev Tools debugger:
111-
112-
![Node inspect Chrome DevTools](/_static/tutorial/debugging/node-inspect-chrome-dev-tools.png)
113-
114-
Other debugger interfaces [are also available](https://nodejs.org/en/docs/inspector), like a CLI debugger or the VSCode debugger.
115-
116-
This is helpful for debugging issues that occur in Emscripten JavaScript interface. The next section describes how to debug issues inside the Emscripten-generated WebAssembly.
117-
118-
## Chromium-based browsers
119-
120-
Recent Chromium-based browsers have support for debugging C++-based WebAssembly in the browser. With a few extra steps described in this section, it is possible to interactively step through and inspect C++-compiled WebAssembly running in the browser.
121-
122-
WebAssembly debugging in DevTools requires a few extra setup steps from a default browser installation.
123-
124-
First, [install the Chrome WebAssembly Debugging extension](https://goo.gle/wasm-debugging-extension).
125-
126-
Next, enable it in DevTools.
127-
128-
Open DevTools -> Click the *gear (⚙)* icon in the top right corner -> go to the *Experiments* panel -> and tick *WebAssembly Debugging: Enable DWARF support*.
129-
130-
![Enable Wasm Debugging](/_static/tutorial/debugging/enable-chrome-wasm-debugging.png)
131-
132-
After exitting Settings, you will be prompted to reload DevTools -- reload.
133-
134-
Next, open the options for Chrome WebAssembly Debugging extension:
135-
136-
![Wasm Debugging Options](/_static/tutorial/debugging/devtools-options.png)
137-
138-
Since itk-wasm performs builds in a clean Docker environment, the debugging source paths in the Docker environment are different than the paths on the host system. The debugging extension has a path substitution system that can account for these differences. In the Docker image, the directory where `itk-wasm` is invoked is mounted as `/work`. Substitute `/work` with the directory where the `itk-wasm` CLI is invoked. For example, if `itk-wasm` was invoked at `/home/matt/src/itk-wasm/examples/Debugging`, then:
139-
140-
![Path substitution](/_static/tutorial/debugging/path-substitution.png)
141-
142-
Build the project with itk-wasm and the `Debug` `CMAKE_BUILD_TYPE` to include DWARF debugging information:
143-
144-
![Emscripten build Debug](/_static/tutorial/debugging/emscripten-build-debug.png)
145-
146-
Here we load and run the WebAssembly with a simple HTML file and server:
147-
148-
```html
149-
<html>
150-
<head>
151-
<script src="https://cdn.jsdelivr.net/npm/itk-wasm@1.0.0-a.11/dist/umd/itk-wasm.js"></script>
152-
</head>
153-
<body>
154-
<p>This is an example to demonstrate browser-based debugging of
155-
C++-generated WebAssembly. For more information, please see the
156-
<a target="_blank" href="https://wasm.itk.org/examples/debugging.html">associated
157-
documentation</a>.</p>
158-
159-
<script>
160-
window.addEventListener('load', (event) => {
161-
const pipeline = new URL('emscripten-build-debug/DebugMe', document.location)
162-
itk.runPipeline(null, pipeline)
163-
});
164-
</script>
165-
166-
</body>
167-
</html>
168-
```
169-
170-
![HTTP Server](/_static/tutorial/debugging/http-server.png)
171-
172-
And we can debug the C++ code in Chrome's DevTools debugger along side the executing JavaScript!
173-
174-
![Debug C++ DevTools](/_static/tutorial/debugging/debug-cxx-devtools.png)
1+
# Debugging WebAssembly
2+
3+
Effective debugging results in effective programming. **itk-wasm** makes effective debugging of WebAssembly possible.
4+
5+
This example walks through the different techniques that can be used with itk-wasm to debug WebAssembly during development.
6+
7+
We will debug the following C++ code:
8+
9+
```cpp
10+
#include <iostream>
11+
12+
int main() {
13+
std::cout << "Hello debugger world!" << std::endl;
14+
15+
const char * wasmDetails = "are no longer hidden";
16+
17+
const int a = 1;
18+
const int b = 2;
19+
const auto c = a + b;
20+
21+
// Simulate a crash.
22+
abort();
23+
return 0;
24+
}
25+
```
26+
27+
[The example](https://github.com/InsightSoftwareConsortium/itk-wasm/tree/main/examples/debugging) provides npm scripts as a convenient way to execute debugging commands that you may also invoke directly in a command line shell.
28+
29+
To run these examples, first [install and test](./hello_world) Podman or Docker and Node/NPM. Then, install the package dependencies and run the example commands.
30+
31+
```
32+
cd itk-wasm/examples/Debugging/
33+
npm install
34+
npm run <name>
35+
```
36+
37+
where `<name>` is the npm script. Available names can be found by calling `npm run` without any arguments.
38+
39+
## Native
40+
41+
The CMake-based itk-wasm build system tooling enables the same C++ build system configuration and code to be reused when building a native system binary or a WebAssembly binary. As a result, native binary debugging tools, such as [GDB](https://sourceware.org/gdb/), [LLDB](https://lldb.llvm.org/), or the [Visual Studio debugger](https://docs.microsoft.com/en-us/visualstudio/debugger/?view=vs-2022).
42+
43+
We can build the project's standard CMake build configuration,
44+
45+
```cmake
46+
cmake_minimum_required(VERSION 3.10)
47+
project(DebuggingWebAssemblyExample)
48+
49+
add_executable(DebugMe DebugMe.cxx)
50+
```
51+
52+
with standard CMake commands,
53+
54+
![Native build](/_static/tutorial/debugging/native-build.png)
55+
56+
The native binary can then be debugged in the standard way. For example, with `gdb` on Linux:
57+
58+
![Native debug Linux](/_static/tutorial/debugging/native-debug-linux.png)
59+
60+
## WASI
61+
62+
The most direct way to debug WebAssembly is through the [WebAssembly System Interface (WASI)](https://wasi.dev/). In itk-wasm we can build to WASI with the [WASI SDK](https://github.com/WebAssembly/wasi-sdk) by specifying the `itkwasm/wasi` toolchain image. A backtrace can quickly be obtained with the `itk-wasm` CLI. Or, a fully fledged debugger session can be started with LLDB.
63+
64+
First, build to WASI WebAssembly with debugging symbols available:
65+
66+
![WASI debug build](/_static/tutorial/debugging/wasi-build-debug.png)
67+
68+
Then, the `itk-wasm` CLI can conveniently run the Wasm binary with the included WASI runtime:
69+
70+
![Run WASI debug](/_static/tutorial/debugging/run-wasi-debug.png)
71+
72+
We can see that `abort` is called in the `main` function at line 13 in `DebugMe.cxx`.
73+
74+
A full debugging session is also possible after [LLDB](https://lldb.llvm.org/) >= 13 and [Wasmtime](https://wasmtime.dev/) are installed.
75+
76+
![LLDB WASI debug](/_static/tutorial/debugging/lldb-wasi-debug.png)
77+
78+
**Note:** when calling `wasmtime` directly and passing local files into a pipeline, `--dir` arguments must be set. This gives `wasmtime` permission to access the directories containing the files. This is required due to WASI's [capability-based security](https://en.wikipedia.org/wiki/Capability-based_security) model. For example, if a file path starts with `./`, then add `--dir ./` arguments to the `wasmtime` invocation. `--dir` can be specified multiple times.
79+
80+
## Node.js
81+
82+
When debugging WebAssembly built with the itk-wasm Emscripten toolchain, set the `CMAKE_BUILD_TYPE` to `Debug` as is required to debug native builds.
83+
84+
As with native builds, this builds debugging symbols, the human-readable names of functions, variables, etc., into the binary. This also adds support for C++ exceptions and retrieving the string name associated with exceptions. Without this itk-wasm instrumentation, a C++ exception will through an error with an opaque integer value. And, Emscripten JavaScript WebAssembly bindings will not be minified, which facilitates debugging.
85+
86+
When built with the default `Release` build type:
87+
88+
![Emscripten build Release](/_static/tutorial/debugging/emscripten-build-release.png)
89+
90+
the JavaScript support code is minified, and difficult to debug:
91+
92+
![Run Node Release](/_static/tutorial/debugging/run-node-release.png)
93+
94+
However, when built with the `Debug` build type:
95+
96+
![Emscripten build Debug](/_static/tutorial/debugging/emscripten-build-debug.png)
97+
98+
a useful backtrace can be obtained:
99+
100+
![Run Node Debug](/_static/tutorial/debugging/run-node-debug.png)
101+
102+
In order to run a debugger with Node, add the `--inspect-brk` flag when invoking `node`:
103+
104+
![Node inspect](/_static/tutorial/debugging/node-inspect.png)
105+
106+
This will pause execution on start a debugging remote interface. To connect to the remote interface with a Chromium browser, visit `chrome://inspect` and click the *inspect* link on the corresponding *Remote Target*:
107+
108+
![Node inspect Remote Target](/_static/tutorial/debugging/node-inspect-remote-target.png)
109+
110+
This will open the Chrome Dev Tools debugger:
111+
112+
![Node inspect Chrome DevTools](/_static/tutorial/debugging/node-inspect-chrome-dev-tools.png)
113+
114+
Other debugger interfaces [are also available](https://nodejs.org/en/docs/inspector), like a CLI debugger or the VSCode debugger.
115+
116+
This is helpful for debugging issues that occur in Emscripten JavaScript interface. The next section describes how to debug issues inside the Emscripten-generated WebAssembly.
117+
118+
## Chromium-based browsers
119+
120+
Recent Chromium-based browsers have support for debugging C++-based WebAssembly in the browser. With a few extra steps described in this section, it is possible to interactively step through and inspect C++-compiled WebAssembly running in the browser.
121+
122+
WebAssembly debugging in DevTools requires a few extra setup steps from a default browser installation.
123+
124+
First, [install the Chrome WebAssembly Debugging extension](https://goo.gle/wasm-debugging-extension).
125+
126+
Next, enable it in DevTools.
127+
128+
Open DevTools -> Click the *gear (⚙)* icon in the top right corner -> go to the *Experiments* panel -> and tick *WebAssembly Debugging: Enable DWARF support*.
129+
130+
![Enable Wasm Debugging](/_static/tutorial/debugging/enable-chrome-wasm-debugging.png)
131+
132+
After exitting Settings, you will be prompted to reload DevTools -- reload.
133+
134+
Next, open the options for Chrome WebAssembly Debugging extension:
135+
136+
![Wasm Debugging Options](/_static/tutorial/debugging/devtools-options.png)
137+
138+
Since itk-wasm performs builds in a clean Docker environment, the debugging source paths in the Docker environment are different than the paths on the host system. The debugging extension has a path substitution system that can account for these differences. In the Docker image, the directory where `itk-wasm` is invoked is mounted as `/work`. Substitute `/work` with the directory where the `itk-wasm` CLI is invoked. For example, if `itk-wasm` was invoked at `/home/matt/src/itk-wasm/examples/Debugging`, then:
139+
140+
![Path substitution](/_static/tutorial/debugging/path-substitution.png)
141+
142+
Build the project with itk-wasm and the `Debug` `CMAKE_BUILD_TYPE` to include DWARF debugging information:
143+
144+
![Emscripten build Debug](/_static/tutorial/debugging/emscripten-build-debug.png)
145+
146+
Here we load and run the WebAssembly with a simple HTML file and server:
147+
148+
```html
149+
<html>
150+
<head>
151+
<script src="https://cdn.jsdelivr.net/npm/itk-wasm@1.0.0-a.11/dist/umd/itk-wasm.js"></script>
152+
</head>
153+
<body>
154+
<p>This is an example to demonstrate browser-based debugging of
155+
C++-generated WebAssembly. For more information, please see the
156+
<a target="_blank" href="https://wasm.itk.org/examples/debugging.html">associated
157+
documentation</a>.</p>
158+
159+
<script>
160+
window.addEventListener('load', (event) => {
161+
const pipeline = new URL('emscripten-build-debug/DebugMe', document.location)
162+
itk.runPipeline(null, pipeline)
163+
});
164+
</script>
165+
166+
</body>
167+
</html>
168+
```
169+
170+
![HTTP Server](/_static/tutorial/debugging/http-server.png)
171+
172+
And we can debug the C++ code in Chrome's DevTools debugger along side the executing JavaScript!
173+
174+
![Debug C++ DevTools](/_static/tutorial/debugging/debug-cxx-devtools.png)

0 commit comments

Comments
 (0)