The basics of using Cheerp

Cheerp is a toolchain that includes executables like clang (C compiler) and clang++ (C++ compiler) in its bin directory. We run these executables to compile C and C++ code to JavaScript and WebAssembly.

Hello world

Let’s build a ‘Hello world’ program to see the basics of using Cheerp.

#include <cheerp/clientlib.h>
[[cheerp::genericjs]] // Required when using browser APIs like console.log
void webMain() {
client::console.log("Hello, world!");

We can compile this with Cheerp by running the following command:

Terminal window
$ /opt/cheerp/bin/clang++ hello.cpp -o hello.js

(If this command fails and outputs “file or command not found”, you need to install Cheerp.)

This will produce hello.js and hello.wasm files. The JavaScript file will fetch and execute the WebAssembly file.

Using the output


To run the output in a browser environment, you can include it as a script in an HTML file:

<!doctype html>
<title>Hello Cheerp</title>
<script src="hello.js" async defer></script>

Then open the HTML file in a browser from your filesystem. Notice that this doesn’t work - due to security reasons, hello.js is not allowed to fetch hello.wasm when the URL uses the file:// scheme.

Instead, run an HTTP server and open the page there. For example:

Terminal window
$ npx http-server

You should see “Hello, world!” in the JavaScript console (usually opened with F12).

This sort of server is fine for development. In production, you will probably be using a web server like nginx, Apache, or similar, which will all work fine.


You can run the output directly in a runtime like Node.js:

Terminal window
$ node hello.js
Hello, world!

In CommonJS modules (i.e. not JavaScript modules), you can also require it from another file:

require("./hello.js"); // Hello, world!

If you are using JavaScript modules in Node.js, or a runtime that uses them by default like Deno, see below.

Command-line options


To optimise the output, pass a standard optimisation flag like -O3. Cheerp does not require the use of any post-compilation optimisation tools such as wasmopt.

JavaScript Modules

To output JavaScript modules, use -cheerp-make-module=es6:

Terminal window
$ /opt/cheerp/bin/clang++ hello.cpp -o hello.js -cheerp-make-module=es6

The default export of the module is a function which returns a Promise. The promise resolves when the WebAssembly module has been loaded and its main function has been executed.

You can import it from another module like this:

<script type="module">
import init from "./hello.js";
await init(); // Hello, world!

Other options

Find out more about the available command-line options.

Other examples

You find more examples in the cheerp-meta repository.

Was this page helpful?
Suggest changes