maiaCpp

1.3.3 verified Fri May 01 auth: no javascript

MaiaCpp (WebCpp) is a C++98 to C transpiler that translates a restricted subset of C++98 to C code, which can then be further compiled to WebAssembly via the MaiaC toolchain. Current stable version is 1.3.3. The project includes a CLI wrapper (webcpp.sh) and supports generating AST (XML, JSON, tree), C output, JS wrapper, WAT, and WASM. It integrates with MaiaC for WebAssembly generation and provides Node.js and browser runners. Differentiators: focuses on a minimal C++98 subset suitable for embedded or WebAssembly use cases, with a migration guide from legacy runner scripts to a dist-oriented flow.

Common errors

error Error: Could not find MaiaC binary. Please install MaiaC first. ↓

cause MaiaC is not installed or not in PATH.

fix

Install MaiaC from its repository (https://github.com/souzamonteiro/maiac) and ensure webc is accessible.

error SyntaxError: Unexpected token (expected ;) at line X col Y ↓

cause C++98 code uses constructs not supported by the transpiler.

fix

Simplify code to C++98 subset; avoid templates, exceptions (except try/catch limited), RTTI, etc.

error Error: output directory does not exist: ./out ↓

cause The output directory must exist or --out-dir must be specified.

fix

Create the directory or use --out-dir to specify an existing path.

error Error: --file option required when not using default test.cpp ↓

cause The wrapper expects a file input via --file flag.

fix

Use --file <path> to specify the input C++ file.

Warnings

breaking Migration from legacy run-* scripts requires '--mode legacy' flag. New dist-oriented flow uses --mode dist. ↓

fix Update your scripts: add '--mode legacy' to maintain old behavior, or migrate to dist mode.

deprecated Legacy wrapper scripts (run-test-node.sh, run-wasm-browser.sh) are deprecated in favor of the unified run-test-cpp.sh and webcpp.sh. ↓

fix Use run-test-cpp.sh --target all or webcpp.sh for new workflows.

gotcha The C++98 subset is limited; not all C++98 features are supported. Check test_cpp98_extended.cpp for coverage. ↓

fix Refer to test files and documentation for supported features. Avoid using unsupported constructs.

gotcha The cpp-compiler.js only outputs C code; further steps (WAT/WASM) require MaiaC (webc) installed separately. ↓

fix Ensure MaiaC is available in the environment when generating WAT or WASM.

gotcha Default path is C++ -> C (MaiaCpp) -> WAT/WASM (MaiaC). Using --js-out requires MaiaC's webc. ↓

fix If JS output is needed, ensure the MaiaC toolchain is properly installed and webcpp.sh forwards the --js-out flag.

Install

npm install maiacpp

yarn add maiacpp

pnpm add maiacpp

Quickstart

Basic usage of maiaCpp: transpile a C++98 file to C, then generate WASM, and create a distributable package.

#!/bin/bash
# Transpile a C++98 file to C and then to WASM using the wrapper
# Ensure you have Node.js >=18 and the repo cloned
cd /path/to/maiacpp

# Simple transpilation: C++ -> C
node compiler/cpp-compiler.js --file compiler/examples/test.cpp --c-out out/test.c

# Full pipeline: C++ -> C -> WAT -> WASM via webcpp.sh
./bin/webcpp.sh --file compiler/examples/test.cpp --all --out-dir ./out

# Generate distribution package (browser + Node runner)
./bin/webcpp.sh --file compiler/examples/test.cpp --dist --out-dir ./dist --name testapp

# Run Node dist immediately
./bin/webcpp.sh --file compiler/examples/test.cpp --dist-run --out-dir ./dist --name testapp