Developer’s guide

There are two options for creating a program running in exaequOS:

  1. Using an interpreter inside exaequOS (lua, bwbasic and more to come)

  2. Developping a C/C++ program on the host machine using the emscripten-exa toolchain.

The objective is to embed the emscripten-exa toolchain directly in exaequoOS.

Supported languages

C/C++

Programs written in C/C++ are compiled on your hoost machine with emscripten-exa toolchain, a modified version of emscripten (see below), in order to generate WebAssembly binaries (and some Javascript). These are the fastest programs that can be run in exaequOS. They can be pure console programs or using frame buffer or using Wayland protocol (buffer mode or OpenGL ES 3 mode).

For using OpenGL ES 3 (i.e WebGL 2), the user can be helped by GLFW3 library or Raylib.

Lua

Lua interpreter is installed in exaequOS and can either interpret lua files (edited by vim or ed) or can interpret user commands on the fly (CLI, command-line interface).

Lua interpreter

Raylib binding

Raylib graphics library is available in Lua by adding at the first line of the lua file

require "raylib_lua"

Most of the draw functions are available but not all the functions of the library. Do not hesitate to ask. You can check some examples in the store (minesweeper, geom).

BASIC

User can also create BASIC programs that can be interpreted by bwbasic. In a same way as Lua, bwbasic can either interpret basic files or user commands with the CLI.

BWBASIC interpreter

emscripten-exa toolchain

The emscripten-exa toolchain is accessible on GitHub.

Installation

Using git, you can clone the repository into your host machine. In order to use emcc or em++ compiler commands, you also need to install python3, nodejs, clang/llvm toolchain, binaryen, cmake. You can check the content of the Dockerfile for the full list of dependencies (see below).

Dockerfile

The Dockerfile is accessible on GitHub. It allows you to directly create a docker image on your host machine and to compile your apps in this docker.

epm - exaequOS package manager

It is a Python script located in emscripten-exa/third_party/epm. It allows to search, install and create packages. Example of command for searching a package provided by user exaequOS:

$ python3 epm.py search @exaequOS

Output should look like this:

Search package @exaequos in exaequOS store
4 package(s) found

ncurses - 6.4.0 - ncurses library - by exaequOS
glfw - 3.4.0 - GLFW library - by exaequOS
exa-wayland - 0.0.1 - Wayland client library - by exaequOS
raylib - 5.0.0 - Raylib game engine - by exaequOS
----------

Example of command for installing packages:

$ python3 epm.py install exa-wayland glfw raylib

Packages are installed in the directory: <current dir>/exapkgs/

Command for listing the installed packages::

$ python3 epm.py list

pkg-config

You shall set the PKG_CONFIG_PATH with the directory containing the .pc files: <current dir>/exapkgs/pkconfigs

example of command for compiling an app using glfw library:

$ emcc main.c `pkg-config --libs --cflags exa-wayland glfw` -o exa/test_glfw.js

Running the compiled application

emscripten-exa toolchain will generate (in your host machine) two files: <app name>.js and <app name>.wasm. There shall be accessible to exaequOS.

Local HTTP server

An HTTP server (port 7777) shall run in your host machine in order to serve the application files (exa.html, <app name>.js and <app name>.wasm). Here is an example of file tree that allows exaequOS to find and execute your application:

root server directory
└── media
    └── localhost
        └── <app name>
            └── exa
                ├── exa.html
                ├── <app name>.js
                └── <app name>.wasm

exa.html file shall look like:

<!doctype html>
<html lang="en-us">
<head>
  <meta charset="utf-8">
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <title>Emscripten-Generated Code</title>

  <style>

    html, body {

      margin : 0;
      padding: 0;
      border: none;
      width: 100%;
      height: 100%;
    }

  </style>
</head>

<body>

  <script async type="text/javascript" src="havoc.js"></script>
</body>

</html>

You need to replace “havoc.js” by the generated js file name.

/media/localhost

In order to execute the application, you need to open a terminal window and type (after $):

exaequos:~ $ /media/localhost/<app name>

Publishing to the store

Register and connect to exaequos.com

In order to publish an app on the store, you need to first signup and connect to the platform.

signup

exapkg

Note

Not applicable for app compiled on your host machine using emcc. Use epm in that case. See below

Once connected, you have to change the current working directory to the app directory (/media/localhost/<app name> or /home/<app path>) and to start the command ‘exapkg’:

exaequos:~ $ cd /media/localhost/<app name>
exaequos:/media/localhost/<app name> $ exapkg

The following window appears. You have to fill it and click on create. The app is then published on the store.

exapkg

epm

You can also publish (from your host machine) an app or a library using epm with the following command (launched in the root directory of the app or lib):

$ python3 epm.py create

The directory structure for a library shall look like:

library root directory
├── include
├── lib
└── pkgconfig

exaequOS store

The published app will be found in the following directory:

/usr/store/<user name>/<package name>

And will be found on hte store:

exastore