You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/packaging/docs/webassembly/introduction.md
+62-6Lines changed: 62 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
# WebAssembly with Tolc #
2
2
3
3
In order for `C++` to be called from `javascript` there has to be an interface level. `tolc` generates this level from your already written `C++` interface.
4
-
To be as close to what an engineer would have written, `tolc` generates human readable [`embind11`](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/embind.html#embind).
4
+
To be as close to what an engineer would have written, `tolc` generates human readable [`embind`](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/embind.html#embind).
5
5
This is then compiled to a `.wasm` and a `.js` file that `javascript` can import.
Assuming your library is called `MyLib`, and the bindings should be generated to the directory `wasm-bindings`.
@@ -80,7 +81,8 @@ $ emsdk.bat activate 3.1.3
80
81
81
82
### Configuring Your Project ###
82
83
83
-
Now when configuring your `CMake` project, pass the toolchain flag `-DCMAKE_TOOLCHAIN_FILE=${EMSDK_DIRECTORY}/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake`. Where you need to replace `${EMSDK_DIRECTORY}` with the directory of the previously downloaded `Emscripten SDK`. Note that the directory separator used by `CMake` is always forward slash (`/`), even on Windows.
84
+
Since `CMake` doesn't have native support for `WebAssembly` we have to provide a `toolchain` file, fortunately for us, `Emscripten` provides us with one.
85
+
When configuring your `CMake` project, just pass the toolchain flag `-DCMAKE_TOOLCHAIN_FILE=${EMSDK_DIRECTORY}/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake`. Where you need to replace `${EMSDK_DIRECTORY}` with the directory of the previously downloaded `Emscripten SDK`. Note that the directory separator used by `CMake` is always forward slash (`/`), even on Windows.
Looking into `build/tolc` you should see `MyLib.js` aswell as `MyLib.wasm`. `MyLib.js` exports a `Promise` that loads the built `WebAssembly`. Here is an example usage:
@@ -103,5 +106,58 @@ loadMyLib().then(MyLib => {
103
106
});
104
107
```
105
108
109
+
Running the file as normal:
110
+
111
+
```shell
112
+
$ node run.js
113
+
```
114
+
115
+
116
+
### Using from a web page ###
117
+
118
+
By default `Emscripten` assumes that you're running your code in a `node` environment (e.g. having access to the filesystem).
119
+
This is not the case on a web page served to a browser. If we add the link flag `-s ENVIRONMENT='web'` to `Emscripten` it will produce a serveable `WebAssembly` module.
120
+
Since `Tolc` exposes a `CMake` build target for the module, all we have to do is add the flag ourself:
121
+
122
+
```cmake
123
+
# Creates the CMake target ${TARGET}_${LANGUAGE}
124
+
# In this case: MyLib_wasm
125
+
tolc_create_bindings(
126
+
TARGET MyLib
127
+
LANGUAGE wasm
128
+
OUTPUT wasm-bindings
129
+
)
130
+
131
+
# Want to deploy to a web page
132
+
set_property(
133
+
TARGET MyLib_wasm
134
+
APPEND_STRING
135
+
PROPERTY LINK_FLAGS "-s ENVIRONMENT='web'")
136
+
```
137
+
138
+
Then we copy over `MyLib.js` and `MyLib.wasm` to our web application and load them as shown previously:
139
+
140
+
```javascript
141
+
// app.js
142
+
constloadMyLib=require('./MyLib');
143
+
144
+
loadMyLib().then(MyLib=> {
145
+
// From here you can use the C++ functions of your library as usual
146
+
MyLib.myCppFunction();
147
+
});
148
+
```
149
+
150
+
Assuming you've loaded the `javascript` within your page:
0 commit comments