diff --git a/CMakeLists.txt b/CMakeLists.txt index 6001353..f88711f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,7 +1,7 @@ cmake_minimum_required(VERSION 3.15) project( Frontend.wasm - VERSION 0.4.2 + VERSION 0.4.3 LANGUAGES CXX) configure_file(docs/ReleaseNotes/version.in diff --git a/docs/ReleaseNotes/v0.4.3.md b/docs/ReleaseNotes/v0.4.3.md new file mode 100644 index 0000000..808717a --- /dev/null +++ b/docs/ReleaseNotes/v0.4.3.md @@ -0,0 +1,5 @@ +# News # + +## Documentation ## + +* More documentation about how to serve the `WebAssembly` with a web server diff --git a/docs/public/introduction.md b/docs/public/introduction.md index c1f27fb..e13a5a1 100644 --- a/docs/public/introduction.md +++ b/docs/public/introduction.md @@ -1,7 +1,7 @@ # WebAssembly with Tolc # 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. -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). +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). This is then compiled to a `.wasm` and a `.js` file that `javascript` can import. ## Using a `C++` library from `javascript` ## @@ -81,7 +81,8 @@ $ emsdk.bat activate 3.1.3 ### Configuring Your Project ### -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. +Since `CMake` doesn't have native support for `WebAssembly` we have to provide a `toolchain` file, fortunately for us, `Emscripten` provides us with one. +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. Example: @@ -90,6 +91,7 @@ Example: $ cmake -S. -Bbuild -DCMAKE_TOOLCHAIN_FILE=${EMSDK_DIRECTORY}/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake ``` + ### Using From `javascript` ### 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: @@ -104,5 +106,58 @@ loadMyLib().then(MyLib => { }); ``` +Running the file as normal: + +```shell +$ node run.js +``` + + +### Using from a web page ### + +By default `Emscripten` assumes that you're running your code in a `node` environment (e.g. having access to the filesystem). +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. +Since `Tolc` exposes a `CMake` build target for the module, all we have to do is add the flag ourself: + +```cmake +# Creates the CMake target ${TARGET}_${LANGUAGE} +# In this case: MyLib_wasm +tolc_create_bindings( + TARGET MyLib + LANGUAGE wasm + OUTPUT wasm-bindings +) + +# Want to deploy to a web page +set_property( + TARGET MyLib_wasm + APPEND_STRING + PROPERTY LINK_FLAGS "-s ENVIRONMENT='web'") +``` + +Then we copy over `MyLib.js` and `MyLib.wasm` to our web application and load them as shown previously: + +```javascript +// app.js +const loadMyLib = require('./MyLib'); + +loadMyLib().then(MyLib => { + // From here you can use the C++ functions of your library as usual + MyLib.myCppFunction(); +}); +``` + +Assuming you've loaded the `javascript` within your page: + +```html + +... + + + +... +``` + + If you want to see what more is supported you can take a look at [the Examples section](./examples.md). diff --git a/tests/README.md b/tests/README.md index 38d4f4f..7386e06 100644 --- a/tests/README.md +++ b/tests/README.md @@ -31,7 +31,7 @@ When the `stage` runs its destructor, the `stage` directory is removed. This can ### EmbindStage ### -The `TestUtil` library provides `EmbindStage` which extends a normal `stage`, and adds some convenient abstractions to test `embind11` built modules. If you don't have a reason to dig, you should probably use a `EmbindStage`. +The `TestUtil` library provides `EmbindStage` which extends a normal `stage`, and adds some convenient abstractions to test `embind` built modules. If you don't have a reason to dig, you should probably use a `EmbindStage`. ## Architecture ## diff --git a/tests/testStage/EmscriptenStage/CMakeLists.txt b/tests/testStage/EmscriptenStage/CMakeLists.txt index a62d88f..fa9606e 100644 --- a/tests/testStage/EmscriptenStage/CMakeLists.txt +++ b/tests/testStage/EmscriptenStage/CMakeLists.txt @@ -35,9 +35,9 @@ target_link_libraries(${target_name} PRIVATE embind) # Export Promise as 'loadm' for module 'm' # -s MODULARIZE=1 sets it as a promise based load # Note that this is necessary for preJS to work properly -set_target_properties( - ${target_name} - PROPERTIES +set_property( + TARGET ${target_name} + PROPERTY LINK_FLAGS - "-s MODULARIZE=1 -s EXPORT_NAME=\"loadm\" --pre-js ${CMAKE_CURRENT_LIST_DIR}/src/pre.js" + "-s MODULARIZE=1 -s EXPORT_NAME=\"loadm\" --pre-js ${CMAKE_CURRENT_LIST_DIR}/src/pre.js " )