Skip to content

Commit 55effe0

Browse files
thewtexthewtex
authored
Merge pull request #1071 from thewtex/podman
Podman
2 parents 50bbd4f + 9f09c44 commit 55effe0

File tree

22 files changed

+1107
-865
lines changed

22 files changed

+1107
-865
lines changed

‎docs/cxx/tutorial/debugging.md‎

Lines changed: 174 additions & 174 deletions
Large diffs are not rendered by default.

‎docs/cxx/tutorial/hello_world.md‎

Lines changed: 158 additions & 158 deletions
Original file line numberDiff line numberDiff line change
@@ -1,158 +1,158 @@
1-
# Hello Wasm World!
2-
3-
## Introduction
4-
5-
This example walks through how to compile a *hello world* executable written in C++ to [WebAssembly](https://webassembly.org/) and how to execute it with standalone WebAssembly runtimes, the Node.js JavaScript runtime, and web browser runtimes!
6-
7-
Before getting started, make sure [Node.js](https://nodejs.org/en/download/) and [Docker](https://docs.docker.com/install/) are installed. On Linux, make sure you can run [`docker` without `sudo`](https://askubuntu.com/questions/477551/how-can-i-use-docker-without-sudo). On Windows, we recommend [WSL 2 with Docker enabled](https://docs.docker.com/desktop/windows/wsl/).
8-
9-
While we recommend following along step-by-step, the complete example can also be found in the [`examples/` directory of the project repository](https://github.com/InsightSoftwareConsortium/itk-wasm/tree/main/examples/hello-world).
10-
11-
Let's get started! 🚀
12-
13-
## Write the code
14-
15-
First, let's create a new directory to house our project.
16-
17-
```sh
18-
mkdir HelloWorld
19-
cd HelloWorld
20-
```
21-
22-
Let's write some code! Populate *hello.cxx* with our Hello World program:
23-
24-
```cpp
25-
#include <iostream>
26-
27-
int main() {
28-
std::cout << "Hello Wasm world!" << std::endl;
29-
return 0;
30-
}
31-
```
32-
33-
Next, provide a [CMake](https://cmake.org/) build configuration at *CMakeLists.txt*:
34-
35-
```cmake
36-
cmake_minimum_required(VERSION 3.16)
37-
project(HelloWorld)
38-
39-
add_executable(hello hello.cxx)
40-
```
41-
42-
## Install itk-wasm
43-
44-
We use the `add_executable` command to build executables with itk-wasm. The [Emscripten](https://kripken.github.io/emscripten-site/) and [WASI](https://github.com/WebAssembly/wasi-sdk) toolchains along with itk-wasm build and execution configurations are contained in itk-wasm [dockcross](https://github.com/dockcross/dockcross) Docker images invoked by the itk-wasm command line interface (CLI). Note that the same code can also be built and tested with native operating system toolchains. This is useful for development and debugging.
45-
46-
Build the program with the itk-wasm CLI, `itk-wasm`. This is shipped with the `itk-wasm` Node.js package. First install *itk-wasm* with the Node Package Manager, `npm`, the CLI that ships with Node.js.
47-
48-
```sh
49-
# Initialize an empty project in the current directory
50-
npm init --yes
51-
npm install itk-wasm@1.0.0-b.106
52-
```
53-
54-
## WASI
55-
56-
Build the project with the WASI `itkwasm/wasi` toolchain in the `./wasi-build/` directory:
57-
58-
```sh
59-
npx itk-wasm -i itkwasm/wasi build
60-
```
61-
62-
A `hello.wasi.wasm` WebAssembly binary is built in the `./wasi-build/` directory.
63-
64-
```sh
65-
❯ ls wasi-build
66-
build.ninja CMakeFiles libwasi-exception-shim.a
67-
cmake_install.cmake hello.wasi.wasm
68-
```
69-
70-
Execute the binary with the `run` `itk-wasm` subcommand.
71-
72-
```sh
73-
❯ npx itk-wasm run wasi-build/hello.wasi.wasm
74-
Hello Wasm world!
75-
```
76-
77-
Congratulations! You just executed a C++ program compiled to WebAssembly. 🎉
78-
79-
The binary can also be executed with other [WASI runtimes](https://github.com/mbasso/awesome-wasm#non-web-embeddings).
80-
81-
## Node.js
82-
83-
For Node.js or the Browser, build the project with the default [Emscripten](https://emscripten.org/) toolchain. The project is built in the `./emscripten-build` directory by default.
84-
85-
```sh
86-
npx itk-wasm build
87-
```
88-
89-
To execute the project, create an `index.mjs` JavaScript file to [invoke the module](../api/node_pipelines.html):
90-
91-
```js
92-
import path from 'path'
93-
import { runPipelineNode } from 'itk-wasm'
94-
95-
const pipelinePath = path.resolve('emscripten-build', 'hello')
96-
const args = []
97-
await runPipelineNode(pipelinePath, args)
98-
```
99-
100-
**Important**: Inside the *package.json* file, we must also add `"type": "module",` to tell Node.js that we have a modern JavaScript project that uses [ES modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules).
101-
102-
And run it!
103-
104-
```sh
105-
❯ npx node ./index.mjs
106-
Hello Wasm world!
107-
```
108-
109-
Congratulations! You just executed a C++ program in JavaScript. 🎉
110-
111-
## Browser
112-
113-
The same Emscripten Wasm module can be executed in a web browser.
114-
115-
Create an HTML file named `index.html` that will call the Wasm module through JavaScript and display its output in the HTML DOM:
116-
117-
```html
118-
<!DOCTYPE html>
119-
<html>
120-
<head>
121-
<title>itk-wasm Browser Hello World!</title>
122-
<meta charset="UTF-8" />
123-
<script src="https://cdn.jsdelivr.net/npm/itk-wasm@1.0.0-b.106/dist/umd/itk-wasm.min.js"></script>
124-
</head>
125-
126-
<body>
127-
<textarea readonly>WebAssembly output...</textarea>
128-
129-
<script>
130-
const outputTextArea = document.querySelector("textarea");
131-
outputTextArea.textContent = "Loading...";
132-
133-
const wasmURL = new URL('emscripten-build/hello', document.location)
134-
const args = []
135-
const inputs = null
136-
const outputs = null
137-
itk.runPipeline(null, wasmURL, args, inputs, outputs).then(
138-
({ stdout, webWorker }) => {
139-
webWorker.terminate()
140-
outputTextArea.textContent = stdout
141-
})
142-
</script>
143-
</body>
144-
</html>
145-
```
146-
147-
Serve the web page and Wasm module with an http server:
148-
149-
```sh
150-
npm install http-server
151-
http-server .
152-
```
153-
154-
And point your browser to `http://127.0.0.1:8080/`.
155-
156-
![Hello Wasm World!](/_static/tutorial/hello_wasm_world.png)
157-
158-
Congratulations! You just executed a C++ program in your web browser. 🎉
1+
# Hello Wasm World!
2+
3+
## Introduction
4+
5+
This example walks through how to compile a *hello world* executable written in C++ to [WebAssembly](https://webassembly.org/) and how to execute it with standalone WebAssembly runtimes, the Node.js JavaScript runtime, and web browser runtimes!
6+
7+
Before getting started, make sure [Node.js](https://nodejs.org/en/download/) and [Podman (recommended)](https://podman.io/docs/installation) or [Docker](https://docs.docker.com/install/) are installed. On Linux, make sure you can run [`podman` or `docker` without `sudo`](https://askubuntu.com/questions/477551/how-can-i-use-docker-without-sudo). On Windows, we highly recommend [Podman](https://podman.io/docs/installation).
8+
9+
While we recommend following along step-by-step, the complete example can also be found in the [`examples/` directory of the project repository](https://github.com/InsightSoftwareConsortium/itk-wasm/tree/main/examples/hello-world).
10+
11+
Let's get started! 🚀
12+
13+
## Write the code
14+
15+
First, let's create a new directory to house our project.
16+
17+
```sh
18+
mkdir HelloWorld
19+
cd HelloWorld
20+
```
21+
22+
Let's write some code! Populate *hello.cxx* with our Hello World program:
23+
24+
```cpp
25+
#include <iostream>
26+
27+
int main() {
28+
std::cout << "Hello Wasm world!" << std::endl;
29+
return 0;
30+
}
31+
```
32+
33+
Next, provide a [CMake](https://cmake.org/) build configuration at *CMakeLists.txt*:
34+
35+
```cmake
36+
cmake_minimum_required(VERSION 3.16)
37+
project(HelloWorld)
38+
39+
add_executable(hello hello.cxx)
40+
```
41+
42+
## Install itk-wasm
43+
44+
We use the `add_executable` command to build executables with itk-wasm. The [Emscripten](https://kripken.github.io/emscripten-site/) and [WASI](https://github.com/WebAssembly/wasi-sdk) toolchains along with itk-wasm build and execution configurations are contained in itk-wasm [dockcross](https://github.com/dockcross/dockcross) Docker images invoked by the itk-wasm command line interface (CLI). Note that the same code can also be built and tested with native operating system toolchains. This is useful for development and debugging.
45+
46+
Build the program with the itk-wasm CLI, `itk-wasm`. This is shipped with the `itk-wasm` Node.js package. First install *itk-wasm* with the Node Package Manager, `npm`, the CLI that ships with Node.js.
47+
48+
```sh
49+
# Initialize an empty project in the current directory
50+
npm init --yes
51+
npm install itk-wasm@1.0.0-b.106
52+
```
53+
54+
## WASI
55+
56+
Build the project with the WASI `itkwasm/wasi` toolchain in the `./wasi-build/` directory:
57+
58+
```sh
59+
npx itk-wasm -i itkwasm/wasi build
60+
```
61+
62+
A `hello.wasi.wasm` WebAssembly binary is built in the `./wasi-build/` directory.
63+
64+
```sh
65+
❯ ls wasi-build
66+
build.ninja CMakeFiles libwasi-exception-shim.a
67+
cmake_install.cmake hello.wasi.wasm
68+
```
69+
70+
Execute the binary with the `run` `itk-wasm` subcommand.
71+
72+
```sh
73+
❯ npx itk-wasm run wasi-build/hello.wasi.wasm
74+
Hello Wasm world!
75+
```
76+
77+
Congratulations! You just executed a C++ program compiled to WebAssembly. 🎉
78+
79+
The binary can also be executed with other [WASI runtimes](https://github.com/mbasso/awesome-wasm#non-web-embeddings).
80+
81+
## Node.js
82+
83+
For Node.js or the Browser, build the project with the default [Emscripten](https://emscripten.org/) toolchain. The project is built in the `./emscripten-build` directory by default.
84+
85+
```sh
86+
npx itk-wasm build
87+
```
88+
89+
To execute the project, create an `index.mjs` JavaScript file to [invoke the module](../api/node_pipelines.html):
90+
91+
```js
92+
import path from 'path'
93+
import { runPipelineNode } from 'itk-wasm'
94+
95+
const pipelinePath = path.resolve('emscripten-build', 'hello')
96+
const args = []
97+
await runPipelineNode(pipelinePath, args)
98+
```
99+
100+
**Important**: Inside the *package.json* file, we must also add `"type": "module",` to tell Node.js that we have a modern JavaScript project that uses [ES modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules).
101+
102+
And run it!
103+
104+
```sh
105+
❯ npx node ./index.mjs
106+
Hello Wasm world!
107+
```
108+
109+
Congratulations! You just executed a C++ program in JavaScript. 🎉
110+
111+
## Browser
112+
113+
The same Emscripten Wasm module can be executed in a web browser.
114+
115+
Create an HTML file named `index.html` that will call the Wasm module through JavaScript and display its output in the HTML DOM:
116+
117+
```html
118+
<!DOCTYPE html>
119+
<html>
120+
<head>
121+
<title>itk-wasm Browser Hello World!</title>
122+
<meta charset="UTF-8" />
123+
<script src="https://cdn.jsdelivr.net/npm/itk-wasm@1.0.0-b.106/dist/umd/itk-wasm.min.js"></script>
124+
</head>
125+
126+
<body>
127+
<textarea readonly>WebAssembly output...</textarea>
128+
129+
<script>
130+
const outputTextArea = document.querySelector("textarea");
131+
outputTextArea.textContent = "Loading...";
132+
133+
const wasmURL = new URL('emscripten-build/hello', document.location)
134+
const args = []
135+
const inputs = null
136+
const outputs = null
137+
itk.runPipeline(null, wasmURL, args, inputs, outputs).then(
138+
({ stdout, webWorker }) => {
139+
webWorker.terminate()
140+
outputTextArea.textContent = stdout
141+
})
142+
</script>
143+
</body>
144+
</html>
145+
```
146+
147+
Serve the web page and Wasm module with an http server:
148+
149+
```sh
150+
npm install http-server
151+
http-server .
152+
```
153+
154+
And point your browser to `http://127.0.0.1:8080/`.
155+
156+
![Hello Wasm World!](/_static/tutorial/hello_wasm_world.png)
157+
158+
Congratulations! You just executed a C++ program in your web browser. 🎉

0 commit comments

Comments
 (0)