Skip to content

tools.md

Latest commit

 

History

History
491 lines (345 loc) · 25.1 KB

tools.md

File metadata and controls

491 lines (345 loc) · 25.1 KB

Tools

Copyright 2017-2026 Moddable Tech, Inc.
Revised: April 17, 2026

About this Document

This document describes the tools provided by Moddable to build, debug, and run JavaScript apps on microcontrollers or in the Moddable simulator.

The tools compile and link JavaScript modules, and prepare assets for specific platforms and specific screens. The only tools you use directly are mcconfig, mcrun, and xsbug. The other tools are used indirectly, through the make file generated by mcconfig and mcrun, but are nevertheless presented here to help you understand what is happening under the hood.

To build the tools themselves, and to build and run apps in the Moddable simulator, you only need standard development tools. To build and run apps on microcontrollers, you also need the microcontrollers toolchains to compile and link C code, and to transfer apps to flash storage. See the Getting Started document for full instructions on how to build the Moddable SDK tools.

Table of Contents

mcconfig

mcconfig is a command line tool that generates a make file based on a manifest, then runs make to build and launch Moddable apps on microcontrollers or in the simulator.

For example:

cd $MODDABLE/examples/piu/balls
mcconfig -d -m

builds and launches the balls example in the simulator,

cd $MODDABLE/examples/piu/balls
mcconfig -d -m -p esp/moddable_two

builds and launches the balls example on Moddable Two, and

cd $MODDABLE/examples/network/http/httpgetjson
mcconfig -d -m -p esp ssid="Public Wi-Fi"

configures an ESP8266 target device to connect to an open Wi-Fi access point called "Public Wi-Fi," then build and launch the httpgetjson example on the device.

A few notes:

  • The first app takes some time to build since all the ESP and XS libraries need to be compiled too.
  • When running a debug build, xsbug needs to be running on your computer for the launch to be successful.
  • See the Manifest document for explanations about manifests.

Arguments

mcconfig [manifest] [-d] [-f format] [-i] [-m] [-o directory] [-p platform] [-r rotation] [-t target] [-v] [-l] [-x xsbug_host:xsbug_port] [ssid="wifi_ssid"] [password="wifi_password"] [screen=screen_driver] [touch=touch_driver]
  • manifest: the manifest file. Defaults to the manifest.json file in the current directory or in the parent directory of the current directory.
  • -d: to build a debug instrumented version and launch the default debugger (usually xsbug)
  • -dx: to build a debug instrumented version and launch the xsbug debugger
  • -dl: to build a debug instrumented version and launch the xsdb debugger
  • -dn: to build a debug instrumented version and not launch any debugger
  • -f format: to select the screen pixel format: gray16, gray256, rgb332, rgb565be or rgb565le. Defaults to rgb565le. See png2bmp for more detail.
  • -i: to build a release instrumented version.
  • -x: overrides the default host and port (localhost:5002) debug builds use to connect to xsbug.
  • -m: to run make automatically, otherwise mcconfig just generates the make file.
  • -o directory: the output directory. Defaults to the $MODDABLE/build directory.
  • -p platform: to select the platform. Consult the documentation for your device target for its platform identifier. The supported values include: esp, esp/moddable_one, esp/moddable_three, esp32, esp32/moddable_two, win, lin, mac, sim/moddable_one, sim/moddable_two, sim/moddable_three, and wasm. Defaults to the host build platform:mac, win or lin.
  • -r rotation: to select the screen rotation: 0, 90, 180 or 270. Defaults to 0. See png2bmp for more detail.
  • -t target: to select the build target: build, deploy, xsbug, clean, or all. Defaults to all. See Build Targets for more detail.
  • -v: to trace all commands executed by make
  • config arguments specified in the form of key-=value or key="value". These are merged into the config section of the manifest. Import the mc/config module to access them. Moddable provided hosts that support networking and/or displays define the following config properties:
    • ssid="wifi ssid" and password="wifi password": to specify network credentials and connect to the network before launching the app.
    • screen=screen_driver and touch=touch_driver: to specify a screen or touch driver. See the examples readme for more information on screen and touch driver configuration.

Note: To generate a release build, omit both -d and -i from the command line.

Note: The -dl option requires Node.js on your build system. You must also first run npm install in $MODDABLE/tools/xsbug-log.

Note: xsdb supports an optional plug-in to allow for customizing output and control flow. Use the environment variable XSBUG_LOGMACHINE to set the path of a custom LogMachine class implementation (that extends Machine). See $MODDABLE/tools/xsbug-log/xsbug-machine.js for the base class, and $MODDABLE/tools/xsbug-log/xsbug-logmachine.js for the default implementation.

Note: The -dn option is currently unsupported on Windows. It will be implemented in the near future.

Build Targets

mcconfig takes an optional -t target argument to specify a build target. The options for the target are:

  • clean: removes build outputs for the app
  • build: builds the app
  • deploy: deploys the app
  • xsbug: connects to the xsbug debugger
  • all: performs the build, deploy, and xsbug steps

When the -t flag is omitted, the default value is all.

When using mcconfig with microcontrollers that use a serial port for JavaScript debugging with xsbug, the deploy, xsbug, and all targets terminate the currently running instance of serial2xsbug, if there is one.

mcrun

mcrun is a command line tool to build mods, scripts that users can install on their IoT products to add new features and change existing behaviors. The inputs to build a mod are JavaScript modules, assets, data, and configuration. These are specified in a manifest. The output is an XS archive file (.xsa extension) containing JavaScript byte code and resource data.

There are a few important differences between mcrun and mcconfig:

  • The manifest used by mcrun must not reference any files which build to native code (e.g. .c or .cpp files) as a mod can only contain JavaScript
  • mcrun supports -t build (but not other target values).
  • config properties are available from the mod/config module instead of mc/config (see the config section of the Manifest documentation for more information about config properties)

Arguments

mcrun [manifest] [-d] [-f format] [-i] [-m] [-o directory] [-p platform] [-r rotation] [-v] [-x xsbug_host:xsbug_port] [ssid="wifi_ssid"] [password="wifi_password"] [screen=screen_driver] [touch=touch_driver]

The command line arguments to mcrun are nearly identical to those for mcconfig, except that mcrun does only suports build as an argument to -t. See the mcconfig Arguments section for a description of each argument.

mcrez

mcrez is a command line tool that includes assets into a resources map. mcrez generates C code that contains the assets themselves and a way to access them.

Moddable apps do not require a file system. Assets are accessed as resources, thanks to the Resource module.

import Resource from "Resource";
import parseBMP from "commodetto/parseBMP";
let bitmap = parseBMP(new Resource("balls-color.bmp"));

Notice that most assets are used directly from flash storage.

Arguments

mcrez files... [-o output] [-r name] [-p platform]
  • files: the paths of the assets to include.
  • -o output: the path of the output directory. Defaults to the current directory.
  • -r name: the name of the generated C file. Defaults to mc.resources.c.
  • -p platform: to select the platform: esp, esp32, win, lin or mac. Defaults to the host build platform:mac, win or lin. esp8266 may be used as an alias for esp.

png2bmp

png2bmp is a command line tool that converts a PNG file into BMP files that Moddable apps can use directly from flash storage.

For instance:

cd $MODDABLE/examples/piu/balls
png2bmp balls.png -o ~/Desktop

creates two files on your desktop:

  • balls-alpha.bmp: a 8-bit gray bitmap that defines the alpha channel.
  • balls-color.bmp: a 16-bit color bitmap that defines the red, green and blue channels.

To be able to use bitmaps directly from flash storage, the bitmaps need to conform to the screen pixel format and rotation. Use the -f option to select the screen pixel format and the -r option to select the screen rotation. png2bmp also takes care of the row bytes constraint related to the screen pixel format. For instance:

cd $MODDABLE/piu/examples/balls
png2bmp balls.png -o ~/Desktop -f gray256 -r 90

Arguments

png2bmp file.png [-a] [-c] [f format] [-o directory] [-r rotation]
  • -a: to create only the alpha bitmap.
  • -c: to create only the color bitmap.
  • -f format: to select the screen pixel format: gray16, gray256, rgb332, rgb565be or rgb565le. Defaults to rgb565le.
  • -o directory: the output directory. Defaults to the current directory.
  • -r rotation: to select the screen rotation: 0, 90, 180 or 270. Defaults to 0.

xsc

xsc is the XS compiler, a command line tool that compiles files containing JavaScript source code (usually stored in a file with a .js extension) into XS binary files containing symbols and byte codes.

By default xsc parses the JavaScript file as an ECMAScript module. Optionally, for compatibility and conformance, xsc can parse the JavaScript file as an ECMAScript program. Moddable apps only use ECMAScript modules.

With the -c option, xsc accepts the @ constructs that reference host functions and host objects. For instance:

class Point @ "Point_destructor" {
	constructor(x, y) @ "Point_constructor"
	moveBy(x, y) @ "Point_moveBy"
	get x() @ "Point_get_x"
	get y() @ "Point_get_y"
}

The Point class creates host objects. The Point_destructor C function is called when the garbage collector destroys such host objects. The Point_constructor C function is called when new Point(x, y) constructs such host objects. The other C functions is be called when accessing properties and calling methods. See XS in C about the implementation of the C functions.

Without the -e option, xsc generates C code that declares XS symbols and the interface of the host functions. Such C code can then be compiled and linked with the implementation of the host functions to build a dynamic library.

With the -e option, xsc embeds the references to host functions and host objects into the XS binary file. It is the linker, xsl, that generates C code for all the modules. That is how Moddable apps work.

Arguments

xsc file [-c] [-d] [-e] [-o directory] [-p] [-r name] [-t directory]
  • file: the path of a .js file to compile.
  • -c: to accept the @ constructs that reference host functions and host objects. With the -c option and without the -e option, xsc generates C code that declares XS symbols, host functions and host objects.
  • -d: to generate the file and line byte codes that allow to debug the JavaScript file.
  • -e: to embed references to host functions and host objects into the XS binary files instead of generating C code. This options is required to compile a JavaScript file into an XS binary file that xsl can link into an XS archive file.
  • -o directory: the path of the output directory. Defaults to the current directory.
  • -p: to parse the JavaScript file as an ECMAScript program.
  • -r name: the name of the output file. Defaults to the name of the input file. The output extension is always .xsb.
  • -t directory: the path of the temporary directory. Defaults to the output directory. With the -c option and without the -e option, xsc generates C code in the temporary directory.

xsl

xsl is the XS linker, a command line tool that links several XS binary files into one XS archive file, and generates C code that declares XS symbols and the interface of the host functions.

With the -p option, xsl can also preload modules and generate C code that defines a read-only XS virtual machine suitable to be cloned to run apps. That is how Moddable apps work.

The C code can then be compiled and linked with the implementation of the host functions to build a dynamic library or an executable.

Arguments

xsl files... [-a name] [-b directory] [-c creation] [-o directory] [-p modules]... [u url]
  • files: the paths of the XS binary files to link.
  • -a name: the name of the XS archive file. Defaults to a.
  • -b directory: the path of the base directory. Defaults to the output directory. The names of the modules in the archive are the paths of the XS binary files, relative to the base directory. It is an error to link XS binary files which are not directly or indirectly inside the base directory.
  • -c creation: the parameters used to create the cloned machines.
  • -o directory: the path of the output directory. Defaults to the current directory.
  • -p module: the name of a module to preload. Use one -p module option by module to preload.
  • -r name: the name of the output file. Defaults to mc.
  • -s feature: the name of a feature to strip. Use one -s feature option by feature to strip, use s * to strip all unused features.
  • -u url: the base URL of the modules in the archive. Defaults to /.

mcbundle

mcbundle is a command line tool to build and package app archives for the Moddable Store.

mcbundle uses the bundle object of the app manifest. Here is a sample bundle object, taken from the countdown example:

"bundle": {
	"id": "tech.moddable.countdown",
	"devices": [
		"esp/moddable_one",
		"com.moddable.two"
	],
	“custom”: “./store/custom”,
	“icon”: “./store/icon.png”
}

To bundle an app archive for the countdown example, you would use the following mcbundle command:

cd $MODDABLE/examples/piu/countdown
mcbundle -d -m -o $MODDABLE/build/tmp

This builds the countdown app for two devices and package the targets into one app archive.

mcbundle generates and execute a shell script, tech.moddable.countdown.sh. The shell script invokes mcconfig once for each target platform to build the app, then copies the targets, icon and custom preferences dialog boxes into the app archive folder. The name of the app archive folder matches the id property of the bundle object: tech.moddable.countdown.

tech.moddable.countdown
	com.moddable.one
		main.bin
	com.moddable.two
		bootloader.bin
		partition-table.bin
		xs_esp32.bin
	custom
		config
			icon.png
			index.html
	icon.png

Eventually, the app archive folder is compressed into the app archive file, tech.moddable.countdown.zip

The shell script, the app archive folder, and the app archive file are located in $MODDABLE/build/tmp.

mcbundle requires the MODDABLE environment variable, the IDF_PATH environment variable for ESP32 devices and the EMSDK environment variable for the Wasm simulator

Arguments

mcbundle [manifest] [-d] [-m] [-o directory]
  • manifest: the manifest file. Defaults to the manifest.json file in the current directory.
  • -d: to build debug instrumented versions.
  • -m: to run bash automatically, otherwise mcbundle just generates the shell script.
  • -o directory: the output directory. Defaults to the current directory.

mchex

mchex is a command line tool to convert a file to the Intel Hexadecimal Object File Format.

Arguments

mchex file -a address [-n name] [-o directory]
  • file: the file to convert.
  • -n name: the output filename. .hex is appended.
  • -o directory: the output directory. Defaults to the current directory.

Simulator

The hardware simulator hosts an XS machine to run Moddable apps in a simulator screen on macOS, Linux, and Windows. The simulator is named mcsim.

A video demonstration of the simulator is available here.

For the Moddable simulator, Moddable apps are dynamic libraries (mc.so or mc.dll) built by mcconfig. The simulator loads such dynamic libraries and executes their main module.

The make file generated by mcconfig automatically launches Moddable apps in the simulator.

  • The Show/Hide Controls item of the View menu toggles the controls pane on the left side of the simulator window. The controls shows depend on which device simulator is in use.
  • The Show/Hide Info item of the View menu toggles the Information bar at the bottom of the simulator window. The Information bar shows the name of the currently running application, screen size, and pixel format.
  • The 0° / 90° / 180° / 270° items of the View menu rotate the device simulator. The Rotate button in the top-right corner also rotates the device simulator.
  • The Device pop-up in the top-left corner of the simulator window selects the device to simulate.
  • The Mode button in the top-right corner selects either light or dark mode.

When using the simulator for debugging, the xsbug debugger shows are two tabs: one for the application running in the simulator and another for the device simulator. The device simulator tab is always named mcsim; the name of the application tab depends on the project running, such as balls or helloworld.

xsdb

xsdb is a command-line JavaScript debugger modeled on the venerable gdb. xsdb complements the Moddable SDK's xsbug GUI debugger. xsdb works with JavaScript running on embedded devices and in the Moddable SDK simulator.

xsdb is designed for three audiences:

  1. Embedded software developers already familiar with gdb
  2. Developers creating tools and workflows that need to interact with an on-device debugger
  3. Code generators, such as LLMs, that need to inspect the device state during execution

Note: xsdb is implemented using Node. Before running it the first time, you must execute npm install.

cd $MODDABLE/tools/xsbug-log
npm install

Invoking xsdb

To use xsdb, pass -dl to mcconfig and mcconfig when building your project:

mcconfig -dl -m -p esp32/moddable_six
mcrun -dl -p sim

Note that mcrun does not yet support xsdb on all targets.

Output mode

To support diverse uses, xsdb has two output modes: test and JSON. Text mode generates output similar to gdb. JSON mode outputs structured JSON data which can be reliably parsed by code without the fragility of text scraping. JSON output mode adapts gdb's "machine mode" to the JavaScript ecosystem. To set the output mode:

set output text
set output json

Saved state

xsdb automatically saves certain configuration settings and restores them on the next session. State is saved in the project directory in a hidden .xsdb file. State is per-session so each project has its own session state. The state includes breakpoints, output (text or JSON), when to break on exceptions, whether to break at start-up, and some other more obscure settings.

xsdb commands

The built-in help provides a complete list of available xsdb commands. The commands are divided into control flow, breakpoints, inspection, navigation, settings, and control.

(xsdb) help

Exiting

The quit or q command is the preferred way to exit xsdb. You can also use ^D (disconnect). Note that ^C attempts to break execution of the running JavaScript, so it cannot be used to exit xsdb.

Threads / Workers

Workers are how JavaScript implements native threads. xsdb follows the model of gdb and calls these workers "threads":

(xsdb) info threads
  Id   Name               State
* 1    simple             Stopped at /Users/peter/Projects/moddable/examples/base/worker/simple/main.js:23
  3973 simpleworker       Running

Source files

There are significant differences between the JavaScript runtime used by the XS JavaScript engine and the native runtime gdb expects. This difference becomes apparent when setting breakpoints using a file name. gdb "knows" the files your project uses because they are loaded by the runtime. xsdb only learns which files are in use when executed. This means that you sometimes need to provide xsdb a full path, especially at start-up before your target JavaScript has executed.

When you set a breakpoint with a relative path, xsdb tries to find the file by checking the JavaScript source files that have executed. If that fails, it searches your project directory. If your source file isn't found, you can specify it using the full path.

(xsdb) b main.js:5
(xsdb) b modules/parse.ts:10
(xsdb) b /Users/peter/Projects/websockets/protocol.js:55

These same rules apply to the list command.

TypeScript

xsdb supports debugging TypeScript, just as xsbug does.

test-examples

The test-examples tool batch tests Moddable SDK examples or any collection of Moddable SDK projects. The tool works by building, installing, and launching each project found in a recursive search of the specified directory. This is valuable when making significant changes to a host platform, such as updating the host API (ESP-IDF, Zephyr) to a significant new version. It can also identify issues with changes to the Moddable SDK itself (the XS engine, build system, etc.).

A successful launch is evaluated by the absence of an unhandled exception or Promise rejection over several seconds of normal execution. Normal execution is detected by the presence of expected instrumentation logs at expected one-second intervals. This is imperfect, but a useful test. It identifies many problems, including host API conflicts that cause a project to fail to launch, significant increases in memory requirements, and API incompatibilities. Future work may expand this to allow for more precise results.

If an embedded project uses the network, test-examples waits for an IP address to be acquired before considering the application launched and beginning to count instrumentation logs.

Running

Note: test-examples is implemented using Node. Before running it for the first time, you must execute npm install in the $MODDABLE/tools/test-examples directory. Because test-examples uses xsdb (aka xsbug-log), you must execute npm install on it too.

cd $MODDABLE/tools/test-examples
npm install
cd $MODDABLE/tools/xsbug-log
npm install

To run test-examples:

cd $MODDABLE/tools/test-examples
node ./index.js esp32/moddable_six --dir $MODDABLE/examples/base

After a run is complete, test-examples stores report.json in with a complete summary of each test. This includes a detailed log, which can be invaluable in diagnosing failures.

You can also run on the simulator:

node ./index.js sim/moddable_six --dir $MODDABLE/examples/base

If you have set $UPLOAD_PORT in your environment, test-examples respects the setting. This is particularly useful when testing with several devices connected to your computer.

To run a single example, use --example in place of --dir:

node ./index.js sim/moddable_six --example $MODDABLE/examples/base/timers

If you terminate a test run before it is complete, you can resume execution using --continue. This depends on the report.json generated when test-examples exists.

node ./index.js sim/moddable_six --dir $MODDABLE/examples/base --continue

Sometimes you only want to build, but not install and launch. Other times you may want to guarantee a clean build (the default is incremental builds, which is faster for re-testing). Use the --mode and --clean options.

node ./index.js sim/moddable_six --dir $MODDABLE/examples/base --mode build --clean

For tests that run on an embedded device using Wi-Fi, provide the Wi-Fi credentials to test-example and it relays them to mcconfig when building the project.

node ./index.js sim/moddable_six --dir $MODDABLE/examples/network.http --ssid "My Wi-Fi" --password "[secret]"

Implementation notes

test-examples uses xsdb to monitor the execution of the example being tested.