Skip to content

README.md

Latest commit

 

History

History
121 lines (83 loc) · 4.17 KB

README.md

File metadata and controls

121 lines (83 loc) · 4.17 KB
Raw

C++ WebAssembly starter template

C++/CMake WebAssembly Project Template. A minimal, modular C++ monorepo structure with static libraries and unit tests, configured with CMake and Emscripten for building WebAssembly applications. Perfect starting point for creating high-performance web apps or games in C++ that run in the browser.

Project structure

The repository is organized as a monorepo with the following main components:

  • native/: Root for all C++/CMake sources and Emscripten build scripts.
    • libs/: Contains modular C++ libraries (e.g., NlpLib).
  • packages/: TypeScript client and server applications, plus tests.
    • sample/: Example TypeScript application consuming the WebAssembly module.
    • tests/: TypeScript tests for the WebAssembly functionality.

Structure Graph

graph TD
  A[cpp_webassembly_template]
  A --> B[native]
  B --> C[libs]
  C --> D[NlpLib]
  A --> E[packages]
  E --> F[sample]
  E --> G[tests]
Loading
  • native/libs/NlpLib: Example C++ library for NLP/text processing.
  • packages/sample: Loads and uses the generated WebAssembly module.
  • packages/tests: Tests the WebAssembly module from TypeScript.

Prerequisites

To build and run this project, you will need:

  • CMake (version 3.15 or higher)
  • Emscripten SDK (latest recommended version)
  • Node.js (version 18 or higher)
  • Python 3 (required by Emscripten)
  • A C++ compiler (for native builds and tests)
  • A CMake generator (Ninja or Make): the wasm build scripts auto-provision Ninja via pip install ninja if neither is found on PATH, but installing one yourself (e.g. pip install ninja or winget install Ninja-build.Ninja / apt install ninja-build) avoids the extra step
  • vcpkg (optional, for managing C++ dependencies; see vcpkg for installation and usage)

Setup instructions:

  1. Install Emscripten SDK and activate it:

  • The setup expects emsdk installed in the home folder (e.g. ~/emsdk). Overwise, set environment variable EMSDK to the location of your choice.

  • Linux/MacOS:

    git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh

  • Windows:

    git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
emsdk install latest
emsdk activate latest
emsdk_env.bat
  1. Install CMake and Node.js.
  2. Run npm install in the project root to install JavaScript/TypeScript dependencies.

Building and Running

Build Native WebAssembly Module

To build the C++ code to WebAssembly:

npm run build:native

This will invoke CMake and Emscripten to produce the .wasm and JavaScript glue files in the build_wasm directory.

The build scripts (native/build_wasm.bat / native/build_wasm.sh) also need tsc (TypeScript) on PATH to emit WebassemblyTemplate.d.ts, and a CMake generator (Ninja or Make) to actually build. When run via npm run, tsc is picked up automatically from node_modules/.bin; if a build script is run directly, it falls back to the repo's node_modules/.bin and to a pip-provisioned Ninja automatically when neither is already on PATH.

Build and Start the TypeScript Sample App

To build and start the sample TypeScript application that consumes the WebAssembly module:

npm run dev
  • npm run build performs a full build of all packages and native code.
  • npm run dev builds and starts the development server for the sample app.

Run Tests

To run the TypeScript tests for the WebAssembly module:

npm run test

Contributing

Contributions are welcome! Please open issues or submit pull requests for improvements, bug fixes, or new features.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements