Building for the Web using Emscripten

Here is a rough draft for instructions to build and run Ecere applications on the Web.

Web support is still being worked on, and we hope to make this a lot easier/integrated in the future.

So, be warned, there are a lots of steps involved.

First you need to install Emscripten.

On Linux, don't use your distribution version if it is too old (e.g. Debian/Ubuntu are way behind on Emscripten, and we're testing with Emscripten version 1.35). Use the portable installer package.

Make sure that you install and explicitly activate both emscripten and clang using 'emsdk install' and 'emsdk activate' ('emsdk list' to list available versions).

The source of 'emcc' (on Windows) or 'emcc.py' (on Linux) must be tweaked for eC source files to be properly preprocesed:

The '.ec' extension must be added to the list of C_ENDINGS:
C_ENDINGS = ('.c', '.C', '.i', '.ec')

Then you set up the paths to all these in the File/Global Settings/Compilers.

You can start from this sample configuration by dropping it into your Ecere IDE settings directory's 'compilerConfigs'
(~/.ecereIDE/compilerConfigs/ on UNIX, C:\Users\[username]\EcereIDE\compilerConfigs on Windows).

You can otherwise create a new compiler for Emscripten in the Global settings dialog from scratch and select these same paths and options.

The active compiler can be selected in the IDE (Through the second-to-rightmost drop box in the toolbar).

If you use a 64 bit toolchain, make sure to include -t32 in 'Additional eC Compiler Flags' under Option, otherwise things will not be built properly. Alternatively, you can install the 32 bit Ecere binaries (Which can be built with ARCH=x32) and ensure that they have priority in the path.

Also, you will need to build the Ecere library with the Emscripten config. You can add the ecere.epj project (from the Ecere SDK source directory, see links above for source code) to your project's workspace, and build it from there (select 'Emscripten' configuration)

You will also need to build some extra dependencies, to build the Emscripten ecere library successfully:

• FreeType (You can find the source for freetype-2.3.12 included in the sdk/deps/ directory)
• libungif (sdk/deps/libungif-4.1.1)
• libpng (sdk/deps/libpng-1.6.12)
• libjpeg (sdk/deps/jpeg-9a)
• zlib (sdk/deps/zlib-1.2.8)

You should be able to use the Ecere project files (.epj) in there already, just select your proper Emscripten compiler and build for the Release config. The libecere project's Emscripten config refers to the location in there, so it should automatically find them there.

Then you can try to build the chess sample (sdk/samples/games/chess) which already has an Emscripten configuration set up.

The main project configuration currently needs to be a static executable, and include the Ecere library resources in a 'ecere' folder'. Importantly, the OpenGL default shaders must be included in ecere/shaders (default.frag, default.vert).

To be able to link against a static version of libecere, your application should use the 'static' keyword for importing the library, e.g. import static "ecere". This is typically done with a preprocessor definition set per configuration (e.g. ECERE_STATIC). The configuration will need to link against the 'static' version of the ecere library (ecereStatic instead of ecere) and include the dependencies libraries to link, e.g. png z jpeg freetype.

To test the project in a browser, you will need to run it through a web server. You can use the sample HTTP server for this purpose (samples/net/httpserver), but beware as it is not meant to be secure or to be use for prouduction

The files you will need to upload include the .js, .data and .mem . You will also need a .html file to load the script; you can use this chess.html and tweak the reference to the .js and the title (this lets the application's WebGL canvas fill up the entire web page).

If you run into trouble, look at the browser's developer console for hints on what might be going wrong and you can always reach out for help.