README

Cheerp: A C++ compiler for the Web
------------------------------------------

Cheerp is a tool to bring C++ programming to the Web. It can generate a seamless
combination of JavaScript, WebAssembly and Asm.js from a single C++ codebase.

Installation
------------------------------------------

Depending on your platform, cheerp needs to be unpacked in a different path:

Windows

	c:\cheerp\

Mac OS

	/Applications/cheerp

Linux

	/opt/cheerp

In the following instructions  /opt/cheerp/ is assumed.

Usage
------------------------------------------

Cheerp is integrated in the LLVM/clang infrastructure.
To build client side JavaScript code from C++ source files

	/opt/cheerp/bin/clang -O3 -target cheerp <file1.cpp> <file2.cpp> -o <file.js>

Building objects file separately and linking only at the end is also possible.

	/opt/cheerp/bin/clang++ -O3 -c -target cheerp <file1.cpp> -o <file1.bc>
	/opt/cheerp/bin/clang++ -O3 -c -target cheerp <file2.cpp> -o <file2.bc>
	/opt/cheerp/bin/clang++ -target cheerp <file1.bc> <file2.bc> -o <linkedfile.js>

Libraries can be built as well, they are stored using LLVM binary representation

	/opt/cheerp/bin/clang++ -O3 -c -target cheerp <file1.cpp> -o <file1.bc>
	/opt/cheerp/bin/clang++ -O3 -c -target cheerp <file2.cpp> -o <file2.bc>
	/opt/cheerp/bin/llvm-link <file1.bc> <file2.bc> ... -o <library.bc>

A cmake toolchain file is provided in /opt/cheerp/share/cmake/Modules/CheerpToolchain.cmake
it's possible to cross-compile cmake projects for the Cheerp platform using the syntax

	cmake -DCMAKE_TOOLCHAIN_FILE=/opt/cheerp/share/cmake/Modules/CheerpToolchain.cmake <regular arguments>

Please note that, currently, only building static libraries is supported.

Code conventions
------------------------------------------

Global variables and types that are provided by the browser
environment are accessible through the 'client' namespace

	client::document.addEventListener(...)

Of course, being a regular C++ namespace you can reduce
code verbosity by

	using namespace client;

The relevant headers that defines client interfaces are

	#include <cheerp/client.h> //Misc client side stuff
	#include <cheerp/clientlib.h> //Complete DOM/HTML5 interface
	#include <cheerp/webgl.h> //WebGL interface

By convention the method that will be called first on the
client side should have the following signature

	void webMain()

NOTE: As usual in JavaScript programming the script will be
loaded before the DOM is completely loaded, and so webMain will
be called on an incomplete document, to execute a callback after
loading is complete you can do this

	void loadCallback()
	{
		...
	}

	void webMain()
	{
		document.addEventListener("DOMContentLoaded",Callback(loadCallback));
	}

In a similar way you can bind to any other DOM event

Properties of DOM objects are always accessed through setters/getters

	{
		auto body = document.get_body();
	}

Small examples are included in /opt/cheerp/share/cheerp/examples/

Limitations as of this version
------------------------------------------

None known