Skip to content

Latest commit

 

History

History
211 lines (140 loc) · 12 KB

tools.md

File metadata and controls

211 lines (140 loc) · 12 KB
Raw

Tools

Copyright 2017 Moddable Tech, Inc.
Revised: April 8, 2020

Warning: These notes are preliminary. Omissions and errors are likely. If you encounter problems, please ask for assistance.

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 will use directly are mcconfig and xsbug. The other tools are used indirectly, through the make file generated by mcconfig, 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 will only need standard development tools. To build and run apps on microcontrollers, you will also need the microcontrollers toolchains to compile and link C code, and to transfer appsa 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/piu/examples/balls
mcconfig -d -m

will build and launch the balls example in the simulator,

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

will build and launch the balls example on Moddable Zero, and

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

will configure 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 will take some time to build since all the ESP and XS libraries need to be compiled too. Such libraries are shared, so subsequent apps will build faster.
  • 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] [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.
  • -f format: to select the screen pixel format: gray16, gray256, rgb332, rgb565be or rgb565le. Defaults to rgb565le. See png2bmp here under.
  • -i: to build a release instrumented version.
  • -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: esp, esp32, win, lin, mac, gecko/mighty, gecko/giant, gecko/blue or gecko/thunderboard2. 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 here under.
  • -t target: to select the build target: build, deploy, xsbug, clean, or all. Defaults to all. See Build Targets below for more detail.
  • -v: to trace all commands executed by make
  • 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.

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, but does not deploy it
  • deploy: deploys a previously built app without rebuilding
  • xsbug: connect the xsbug debugger to a previously-deployed app
  • all: performs all steps (This is the default value, when the -t flag is omitted)

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.

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/piu/examples/balls
png2bmp balls.png -o ~/Desktop

will create two files on your dektop:

  • 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 JS files into XS binary files containing symbols and byte codes.

By default xsc parses the JS file as an ECMAScript module. Optionally, for compatibility and conformance, xsc can parse the JS 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 will be called when the garbage collector destroys such host objects. The Point_constructor C function will be called when new Point(x, y) constructs such host objects. The other C functions will 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 will generate 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 JS 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 JS 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 JS 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 that will be 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 /.

Simulator

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

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.

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

  • The Screen Test->Touch Mode item of the application menu toggles the touch mode on and off. When the touch mode is on, your track pad is mapped to the simulator screen to test the multitouch features of your app.
  • The File->Open... and File->Close items of the application menu allow you to open and close a Moddable app. You can also drag and drop a Moddable app on the Screen Test icon or window.
  • The File->Get Info menu allows you to inspect the pixel format your app has been built for.
  • The Size menu allows you to change the simulator screen size. The Moddable app quits and relaunches when the simulator screen changes.