Build and Use

This document provides the complete build process for the ElenixOS simulator, including build command descriptions, configuration options, and solutions to common issues.

Build Overview

The ElenixOS simulator uses CMake as the build system, supporting two platforms: Native (local desktop) and WASM (WebAssembly). The default build target is the Native platform.

Build Configuration

Build Types

Build Type	CMake Option	Description
Debug	-DCMAKE_BUILD_TYPE=Debug	Debug mode, enables debug symbols and assertions
Release	-DCMAKE_BUILD_TYPE=Release	Release mode, enables optimizations
MinSizeRel	-DCMAKE_BUILD_TYPE=MinSizeRel	Minimum size release mode

Platform Configuration

Platform	CMake Option	Description
Native	-DEOS_PLATFORM=Native	Local desktop application (default)
WASM	-DEOS_PLATFORM=WASM	WebAssembly platform

Feature Options

Option	Default	Description
USE_FREERTOS	OFF	Enable FreeRTOS real-time kernel
LV_USE_DRAW_SDL	OFF	Enable SDL rendering acceleration
LV_USE_LIBPNG	OFF	Enable libpng PNG decoding
LV_USE_LIBJPEG_TURBO	OFF	Enable libjpeg-turbo JPEG decoding
LV_USE_FFMPEG	OFF	Enable FFmpeg video playback
LV_USE_FREETYPE	OFF	Enable freetype font rendering

Build Steps

Native Platform Build

# Enter project root directory
cd ElenixOS-Simulator

# Create build directory
mkdir build && cd build

# Configure CMake (Debug mode)
cmake .. -DCMAKE_BUILD_TYPE=Debug

# Compile
cmake --build . -j$(nproc)

# Run simulator
./bin/main

Release Mode Build

mkdir -p build-release && cd build-release
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j$(nproc)

WASM Platform Build

WASM build requires the Emscripten toolchain. Ensure Emscripten SDK is installed and activated:

# Install Emscripten SDK (if not already installed)
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh

# Return to project directory, create WASM build directory
cd ElenixOS-Simulator
mkdir -p build-wasm && cd build-wasm

# Configure CMake (WASM platform)
cmake .. -DEOS_PLATFORM=WASM -DCMAKE_BUILD_TYPE=Release

# Compile
cmake --build . -j$(nproc)

# Build artifacts are in build-wasm/bin/ directory
# Use HTTP server to open bin/main.html to run

Enable FreeRTOS

mkdir -p build-freertos && cd build-freertos
cmake .. -DUSE_FREERTOS=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build . -j$(nproc)

Complete Build Process

The following diagram shows the complete build process for the ElenixOS simulator:

Source code (C/C++/JS)
    │
    ├── ElenixOS/          ──┐
    ├── lvgl/              ──┤── CMake compilation ──► elenixos_lib (static library)
    ├── FreeRTOS/          ──┘
    │
    └── main/              ──┬── Linking ──► main (executable)
        ├── main.c          │
        ├── eos_port.c      │
        ├── jerry_port.c    │
        └── mac_api.c       │
                            │
                    Runtime directory structure:
                    bin/
                    ├── main (or main.html)
                    └── fs/
                        ├── .sys/
                        │   ├── config/
                        │   └── res/
                        └── .simulator/

Build Artifacts

After building for Native platform, artifacts are located in build/bin/ directory:

File	Description
main	Simulator executable
fs/	Runtime file system directory (automatically copied by CMake)

After building for WASM platform, artifacts are located in build-wasm/bin/ directory:

File	Description
main.html	Simulator web page
main.js	WASM glue code
main.wasm	WebAssembly binary
static/	Static resource directory

ElenixOS-Tools Development Tool

The project provides the ElenixOS-Tools.py tool script to assist with the development process:

# Run the tool
python3.10 ElenixOS-Tools.py

This script provides the following functionality:

1. Generate lvgl.json: Generate JSON API description file from LVGL source code
2. Generate sni_lv_types.c: Generate type definition file for LVGL JavaScript bindings based on lvgl.json

The tool automatically creates a Python virtual environment and installs dependencies.

Run the Simulator

Native Platform

Execute the build artifact directly:

./bin/main

The simulator window includes:

• Central display area: Simulated watch screen (390x450 pixels)
• Right side Crown: Click to simulate crown press
• Right side Side Button: Click to simulate side button press

WASM Platform

Use an HTTP server to serve the build artifacts:

# Use Python built-in HTTP server
cd build-wasm/bin
python3 -m http.server 8000

# Open http://localhost:8000/build-wasm/bin/main.html in browser

Common Build Issues

CMake Configuration Failure

Error message: Could NOT find SDL2

Solution: Install SDL2 development library, see Environment Setup documentation.

Compilation Error: Header File Not Found

fatal error: 'lvgl/lvgl.h' file not found

Solution: Ensure submodules are correctly initialized:

git submodule update --init --recursive

Linking Error: Undefined Symbols

undefined reference to 'eos_xxx'

Solution: Clean build cache and recompile:

rm -rf build
mkdir build && cd build
cmake ..
cmake --build .

WASM Build: Emscripten Not Found

CMake Error: Could not find CMAKE_ROOT

Solution: Ensure Emscripten environment is correctly activated:

source /path/to/emsdk/emsdk_env.sh

FreeRTOS Build Failure

When enabling FreeRTOS, ensure the compiler supports POSIX threads (pthreads). Linux and macOS usually have built-in support, for Windows it is recommended to use WSL2.

WASM Platform Does Not Support FreeRTOS

When building for WASM, USE_FREERTOS is automatically disabled because the Emscripten environment does not support FreeRTOS's POSIX porting layer.

Next Steps

After successful build, it is recommended to continue exploring in the following order:

1. Read System Architecture to understand ElenixOS design
2. Read Quick Start to understand basic usage
3. Check JS API to start developing applications