diff --git a/CMakeLists.txt b/CMakeLists.txt index 1f838ac..8c7b243 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,7 +1,7 @@ cmake_minimum_required(VERSION 3.15) project( Frontend.wasm - VERSION 0.4.0 + VERSION 0.4.1 LANGUAGES CXX) configure_file(docs/ReleaseNotes/version.in diff --git a/docs/ReleaseNotes/v0.4.1.md b/docs/ReleaseNotes/v0.4.1.md new file mode 100644 index 0000000..215c4b6 --- /dev/null +++ b/docs/ReleaseNotes/v0.4.1.md @@ -0,0 +1,6 @@ +# News # + +## Documentation ## + +* Added a quick guide to using C++ from javascript via WebAssembly + diff --git a/docs/public/introduction.md b/docs/public/introduction.md index 7ef8f5c..a1c1db3 100644 --- a/docs/public/introduction.md +++ b/docs/public/introduction.md @@ -4,7 +4,13 @@ In order for `C++` to be called from `javascript` there has to be an interface l 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). This is then compiled to a `.wasm` and a `.js` file that `javascript` can import. -## Prerequisites ## +## Using a `C++` library from `javascript` ## + +This is a quick guide to using a `C++` library (here called `MyLib`) from `javascript`. We will: + +1. Download and use `Tolc` +2. Download and set up `Emscripten` +3. Use the resulting `WebAssembly` from `javascript` The following works on all supported platforms. On all platforms you need `git` available in your `path`. Commands that should be run from a terminal starts with `$ `, while comments starts with `# `. @@ -13,6 +19,7 @@ The following works on all supported platforms. On all platforms you need `git` Just add the following in a `CMakeLists.txt` below where the library you intend to use from `javascript` is defined: ```cmake +# Download Tolc # Can be ["latest", "v0.2.0", ...] set(tolc_version latest) include(FetchContent) @@ -29,17 +36,17 @@ find_package( ${tolc_entry_SOURCE_DIR} REQUIRED) -tolc_create_translation( +tolc_create_bindings( TARGET MyLib LANGUAGE wasm - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/wasm-bindings) + OUTPUT wasm-bindings) ``` -Assuming your library is called `MyLib`, and the bindings should be generated to `${CMAKE_CURRENT_BINARY_DIR}/wasm-bindings`. +Assuming your library is called `MyLib`, and the bindings should be generated to the directory `wasm-bindings`. ### Downloading `Emscripten` ### -In order to compile your library to `WebAssembly`, you need to download the [`Emscripten compiler`](https://emscripten.org/). This is typically done via their `Emscripten SDK`. Navigate to the directory where you want to install and run the following commands: +In order to compile your library to `WebAssembly`, you need to download the [`Emscripten compiler`](https://emscripten.org/). This is typically done via the `Emscripten SDK`. Navigate to the directory where you want to install and run the following commands: ```shell # Download SDK @@ -71,9 +78,9 @@ $ emsdk.bat install 3.1.3 $ 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`. +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. Example: @@ -82,3 +89,19 @@ 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: + +```javascript +// run.js +const loadMyLib = require('./build/MyLib'); + +loadMyLib().then(MyLib => { + // From here you can use the C++ functions of your library as usual + MyLib.myCppFunction(); +}); +``` + +If you want to see what more is supported you can take a look at [the Examples section](./examples.md). +