Copyright 2017-2024 Moddable Tech, Inc.
改訂： 2024年7月29日
このドキュメントでは、Moddableが提供するツールについて説明します。これらのツールは、マイクロコントローラーやModdableシミュレーター上でJavaScriptアプリを構築、デバッグ、実行するために使用されます。
ツールはJavaScriptモジュールをコンパイル・リンクし、特定のプラットフォームや画面に合わせてアセットを準備します。直接使用するツールはmcconfig、mcrun、xsbugのみです。他のツールは、mcconfigとmcrunによって生成されたmakefileを通じて間接的に使用されますが、何が行われているのかを理解するためにここで紹介します。
ツール自体を構築し、Moddableシミュレーターでアプリを構築・実行するには、標準的な開発ツールのみが必要です。マイクロコントローラー上でアプリを構築・実行するには、Cコードをコンパイル・リンクし、アプリをフラッシュストレージに転送するためのマイクロコントローラーツールチェーンも必要です。Moddable SDKツールを構築する方法の完全な手順については、Getting Started ドキュメントを参照してください。
mcconfig はマニフェストに基づいてmakefileを生成し、make を実行してマイクロコントローラーやシミュレーターでModdableアプリをビルドして起動するコマンドラインツールです。
例えば：
cd $MODDABLE/examples/piu/balls
mcconfig -d -mはシミュレーターで balls のサンプル をビルドして起動し、
cd $MODDABLE/examples/piu/balls
mcconfig -d -m -p esp/moddable_twoはModdable Twoでballsのサンプルをビルドして起動し、
cd $MODDABLE/examples/network/http/httpgetjson
mcconfig -d -m -p esp ssid="Public Wi-Fi"は "Public Wi-Fi" という名前のオープンなWi-Fiアクセスポイントに接続するためにESP8266ターゲットデバイスを設定し、そのデバイス上でhttpgetjsonのサンプルをビルドして起動します。
いくつかの注意点：
- 最初のアプリのビルドには時間がかかります。ESPおよびXSライブラリもコンパイルする必要があるためです。
- デバッグビルドを実行する場合、xsbugがコンピューターで実行されている必要があります。そうでないと起動に成功しません。
- マニフェストについての説明は、Manifestドキュメントを参照してください。
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: マニフェストファイル。デフォルトは現在のディレクトリまたは現在のディレクトリの親ディレクトリにあるmanifest.jsonファイルです。-d: デバッグ用のinstrumentedバージョンをビルドし、デフォルトのデバッガー（通常はxsbug）を起動します。-dx: デバッグ用のinstrumentedバージョンをビルドし、xsbugデバッガーを起動します。-dl: デバッグ用のinstrumentedバージョンをビルドし、xsbug-logデバッガーを起動します。-dn: デバッグ用のinstrumentedバージョンをビルドし、デバッガーを起動しません。-f format: 画面のピクセルフォーマットを選択します：gray16,gray256,rgb332,rgb565beまたはrgb565le。デフォルトはrgb565leです。詳細は png2bmp を参照してください。-i: リリースinstrumentedバージョンをビルドします。-l: xsbugのコンソール出力をxsbugではなくターミナルにログします（下記の注を参照）。-lは-dlに置き換えられて非推奨です。-x: デバッグビルドがxsbugに接続するために使用するデフォルトのホストとポート（localhost:5002）を上書きします。-m: 自動的にmakeを実行します。それ以外の場合、mcconfigはmakeファイルを生成するだけです。-o directory: 出力ディレクトリ。デフォルトは$MODDABLE/buildディレクトリです。-p platform: プラットフォームを選択します。デバイスターゲットのドキュメントを参照して、そのプラットフォーム識別子を確認してください。サポートされている値には、esp,esp/moddable_one,esp/moddable_three,esp32,esp32/moddable_two,win,lin,mac,sim/moddable_one,sim/moddable_two,sim/moddable_three, およびwasmが含まれます。ホストビルドプラットフォームにデフォルトされます：mac,winまたはlin。-r rotation: 画面の回転を選択します：0,90,180または270。デフォルトは0です。詳細は png2bmp を参照してください。-t target: ビルドターゲットを選択します：build,deploy,xsbug,clean, またはall。デフォルトはallです。詳細は Build Targets を参照してください。-v:makeによって実行されるすべてのコマンドをトレースします。key-=valueまたはkey="value"の形式で指定された設定引数。これらはマニフェストのconfigセクションにマージされます。mc/configモジュールをインポートしてアクセスします。Moddableが提供するホストは、ネットワーキングおよび/またはディスプレイをサポートしているため、次の設定プロパティを定義しています：ssid="wifi ssid"およびpassword="wifi password"：ネットワーク認証情報を指定し、アプリを起動する前にネットワークに接続します。screen=screen_driverおよびtouch=touch_driver：画面またはタッチドライバを指定します。画面およびタッチドライバの設定についての詳細は、examples readmeを参照してください。
注意: リリースビルドを生成するには、コマンドラインから
-dと-iを除外してください。
注意:
-lおよび-dlオプションは、ビルドシステムに Node.js が必要です。また、$MODDABLE/tools/xsbug-logでnpm installを実行する必要があります。
注意:
xsbug-logは、出力と制御フローをカスタマイズするためのオプションのプラグインをサポートしています。環境変数XSBUG_LOGMACHINEを使用して、カスタムのLogMachineクラス実装（Machineを拡張する）へのパスを設定します。ベースクラスについては$MODDABLE/tools/xsbug-log/xsbug-machine.jsを、デフォルト実装については$MODDABLE/tools/xsbug-log/xsbug-logmachine.jsを参照してください。
注意:
-dnオプションは現在 Windows ではサポートされていません。近い将来に実装される予定です。
mcconfig はオプショナルな -t target 引数を取り、ビルドターゲットを指定します。ターゲットのオプションは以下の通りです：
clean: アプリのビルド出力を削除しますbuild: アプリをビルドしますdeploy: アプリをデプロイしますxsbug: xsbugデバッガに接続しますall:build、deploy、およびxsbugのステップを実行します
-t フラグが省略された場合、デフォルト値は all です。
mcconfig を使用して、xsbugでJavaScriptデバッグを行うシリアルポートを使用するマイクロコントローラーを使用する場合、deploy、xsbug、および all ターゲットは、実行中のserial2xsbugのインスタンスを終了します（存在する場合）。
mcrun は、mod をビルドするコマンドラインツールです。modは、新しい機能を追加したり、既存の挙動を変更したりするスクリプトで、ユーザーがIoT製品にインストールできます。modをビルドするための入力は、JavaScriptモジュール、アセット、データ、および設定で、これらはマニフェストで指定されます。出力は、JavaScriptバイトコードとリソースデータを含むXSアーカイブファイル（.xsa 拡張子）です。
mcrunとmcconfigの間にはいくつか重要な違いがあります：
mcrunによって使用されるマニフェストは、modがJavaScriptのみを含むことができるため、ネイティブコードにビルドされるファイル（例：.cや.cppファイル）を参照してはいけませんmcrunは-t buildオプションをサポートしています(しかし他のビルドターゲットは未対応です)configプロパティはmc/configの代わりにmod/configモジュールから利用可能です（configプロパティについての詳細はマニフェストのドキュメントのconfigセクションを参照してください）
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]
mcrunのコマンドライン引数はmcconfigのものとほぼ同じですが、mcrunは-tオプションをサポートしていません。各引数の説明については、mcconfig 引数セクションを参照してください。
mcrezはリソースマップにアセットを含めるコマンドラインツールです。mcrezはアセット自体とそれにアクセスする方法を含むCコードを生成します。
Moddableアプリはファイルシステムを必要としません。アセットはResourceモジュールのおかげでリソースとしてアクセスされます。
import Resource from "Resource";
import parseBMP from "commodetto/parseBMP";
let bitmap = parseBMP(new Resource("balls-color.bmp"));ほとんどのアセットはフラッシュストレージから直接使用されることに注意してください。
mcrez files... [-o output] [-r name] [-p platform]files: 含めるアセットのパス。-o output: 出力ディレクトリのパス。デフォルトは現在のディレクトリです。-r name: 生成されるCファイルの名前。デフォルトはmc.resources.cです。-p platform: プラットフォームを選択するために：esp,esp32,win,linまたはmac。ホストビルドプラットフォームにデフォルト設定されています：mac,winまたはlin。esp8266はespのエイリアスとして使用される場合があります。
png2bmpはPNGファイルをModdableアプリがフラッシュストレージから直接使用できるBMPファイルに変換するコマンドラインツールです。
例えば：
cd $MODDABLE/examples/piu/balls
png2bmp balls.png -o ~/Desktopデスクトップ上に2つのファイルを作成します：
balls-alpha.bmp: アルファチャンネルを定義する8ビットグレービットマップ。balls-color.bmp: 赤、緑、青のチャンネルを定義する16ビットカラービットマップ。
フラッシュストレージから直接ビットマップを使用するには、ビットマップが画面のピクセルフォーマットと回転に準拠している必要があります。画面のピクセルフォーマットを選択するには -f オプションを、画面の回転を選択するには -r オプションを使用します。png2bmp は画面のピクセルフォーマットに関連する行バイトの制約も処理します。例えば：
cd $MODDABLE/piu/examples/balls
png2bmp balls.png -o ~/Desktop -f gray256 -r 90
png2bmp file.png [-a] [-c] [f format] [-o directory] [-r rotation]-a: アルファビットマップのみを作成します。-c: カラービットマップのみを作成します。-f format: 画面のピクセルフォーマットを選択します：gray16,gray256,rgb332,rgb565beまたはrgb565le。デフォルトはrgb565le。-o directory: 出力ディレクトリ。デフォルトは現在のディレクトリです。-r rotation: 画面の回転を選択します：0,90,180または270。デフォルトは0。
xscはXSコンパイラで、コマンドラインツールとして、JavaScriptソースコードを含むファイル（通常は.js拡張子のファイルに保存される）を、シンボルとバイトコードを含むXSバイナリファイルにコンパイルします。
デフォルトでは、xscはJavaScriptファイルをECMAScriptモジュールとして解析します。オプションで、互換性と適合性のために、xscはJavaScriptファイルをECMAScriptプログラムとして解析することもできます。ModdableアプリはECMAScriptモジュールのみを使用します。
-cオプションを使用すると、xscはホスト関数やホストオブジェクトを参照する@構文を受け入れます。例えば：
class Point @ "Point_destructor" {
constructor(x, y) @ "Point_constructor"
moveBy(x, y) @ "Point_moveBy"
get x() @ "Point_get_x"
get y() @ "Point_get_y"
}Pointクラスはホストオブジェクトを作成します。ガベージコレクタがそのようなホストオブジェクトを破棄するときにはPoint_destructor C言語の関数が呼ばれます。new Point(x, y)でそのようなホストオブジェクトを構築するときにはPoint_constructor C言語の関数が呼ばれます。他のC言語の関数はプロパティにアクセスしたりメソッドを呼び出したりするときに呼ばれます。C言語の関数の実装についてはXS in Cを参照してください。
-e オプションがない場合、xsc はXSシンボルを宣言し、ホスト関数のインターフェースを宣言するCコードを生成します。そのようなC言語のコードは、ホスト関数の実装とリンクしてコンパイルされ、動的ライブラリを構築することができます。
-e オプションを使用すると、xsc はホスト関数とホストオブジェクトへの参照をXSバイナリファイルに埋め込みます。リンカーである xsl がすべてのモジュールのC言語のコードを生成します。これがModdableアプリが動作する方法です。
xsc file [-c] [-d] [-e] [-o directory] [-p] [-r name] [-t directory]file: コンパイルする.jsファイルのパス。-c: ホスト関数とホストオブジェクトを参照する@構造を受け入れるために使用します。-cオプションがあり、-eオプションがない場合、xsc はXSシンボル、ホスト関数、およびホストオブジェクトを宣言するCコードを生成します。-d: JavaScriptファイルをデバッグするためにファイルと行のバイトコードを生成します。-e: ホスト関数とホストオブジェクトへの参照をXSバイナリファイルに埋め込むために使用します。このオプションは、xsl がXSアーカイブファイルにリンクできるXSバイナリファイルにJavaScriptファイルをコンパイルするために必要です。-o directory: 出力ディレクトリのパス。デフォルトは現在のディレクトリです。-p: JavaScriptファイルをECMAScriptプログラムとして解析します。-r name: 出力ファイルの名前。デフォルトは入力ファイルの名前です。出力拡張子は常に.xsbです。-t directory: 一時ディレクトリのパス。デフォルトは出力ディレクトリです。-cオプションがあり、-eオプションがない場合、xsc は一時ディレクトリにC言語のコードを生成します。
xslはXSリンカーで、コマンドラインツールです。複数のXSバイナリファイルを1つのXSアーカイブファイルにリンクし、XSシンボルとホスト関数のインターフェースを宣言するC言語のコードを生成します。
-pオプションを使用すると、xslはモジュールをプリロードし、アプリを実行するためにクローン可能な読み取り専用のXS仮想マシンを定義するCコードも生成できます。これがModdableアプリの動作方法です。
その後、C言語のコードをコンパイルしてホスト関数の実装とリンクし、動的ライブラリまたは実行可能ファイルをビルドします。
xsl files... [-a name] [-b directory] [-c creation] [-o directory] [-p modules]... [u url]files: リンクするXSバイナリファイルのパス。-a name: XSアーカイブファイルの名前。デフォルトはaです。-b directory: ベースディレクトリのパス。デフォルトは出力ディレクトリです。アーカイブ内のモジュールの名前は、ベースディレクトリに対して相対的なXSバイナリファイルのパスです。ベースディレクトリの直接または間接的に内部にないXSバイナリファイルをリンクすることはエラーです。-c creation: クローンされたマシンを作成するために使用されるパラメータ。-o directory: 出力ディレクトリのパス。デフォルトは現在のディレクトリです。-p module: プリロードするモジュールの名前。プリロードするモジュールごとに-p moduleオプションを使用します。-r name: 出力ファイルの名前。デフォルトはmcです。-s feature: 削除する機能の名前。削除する機能ごとに-s featureオプションを使用し、s *を使用してすべての未使用機能を削除します。-u url: アーカイブ内のモジュールのベースURL。デフォルトは/です。
mcbundle は、Moddable Store用のアプリアーカイブを構築してパッケージするコマンドラインツールです。
mcbundle は、アプリマニフェストの bundle オブジェクトを使用します。以下は、countdown サンプルから取られた bundle オブジェクトのサンプルです：
"bundle": {
"id": "tech.moddable.countdown",
"devices": [
"esp/moddable_one",
"com.moddable.two"
],
“custom”: “./store/custom”,
“icon”: “./store/icon.png”
}
countdown サンプルのアプリアーカイブをバンドルするには、次の mcbundle コマンドを使用します：
cd $MODDABLE/examples/piu/countdown
mcbundle -d -m -o $MODDABLE/build/tmpこれにより、countdown アプリが2つのデバイス用に構築され、ターゲットが1つのアプリアーカイブにパッケージされます。
mcbundle はシェルスクリプト tech.moddable.countdown.sh を生成して実行します。このシェルスクリプトは、アプリを構築するために各ターゲットプラットフォームに対して mcconfig を一度ずつ呼び出し、ターゲット、アイコン、カスタム設定ダイアログボックスをアプリアーカイブフォルダにコピーします。アプリアーカイブフォルダの名前は bundle オブジェクトの id プロパティに一致します：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
最終的に、アプリアーカイブフォルダは tech.moddable.countdown.zip というアプリアーカイブファイルに圧縮されます。
シェルスクリプト、アプリアーカイブフォルダ、およびアプリアーカイブファイルは $MODDABLE/build/tmp に位置しています。
mcbundle は MODDABLE 環境変数、ESP32デバイスのための IDF_PATH 環境変数、およびWasmシミュレータのための EMSDK 環境変数を必要とします。
mcbundle [manifest] [-d] [-m] [-o directory]manifest: マニフェストファイル。デフォルトは現在のディレクトリのmanifest.jsonファイルです。-d: デバッグ用のinstrumentedバージョンでビルドします。-m:bashを自動的に実行するために、それ以外の場合は mcbundle はシェルスクリプトを生成するだけです。-o directory: 出力ディレクトリ。デフォルトは現在のディレクトリです。
mchex は、ファイルをIntel Hexadecimal Object File Formatに変換するコマンドラインツールです。
mchex file -a address [-n name] [-o directory]file: 変換するファイル。-n name: 出力ファイル名。.hexが追加されます。-o directory: 出力ディレクトリ。デフォルトは現在のディレクトリです。
ハードウェアシミュレータは、macOS、Linux、Windows上でModdableアプリをシミュレータ画面で実行するためのXSマシンをホストします。シミュレータはmcsimと名付けられています。
シミュレータのビデオデモンストレーションはこちらで利用可能です。
Moddableシミュレータの場合、Moddableアプリはmcconfigによってビルドされた動的ライブラリ（mc.soまたはmc.dll）です。シミュレータはそのような動的ライブラリをロードし、そのmainモジュールを実行します。
mcconfigによって生成されたmakefileは自動的にシミュレータでModdableアプリを起動します。
- ViewメニューのShow/Hide Controls項目は、シミュレータウィンドウの左側にあるコントロールパネルを切り替えます。表示されるコントロールは使用中のデバイスシミュレータに依存します。
- ViewメニューのShow/Hide Info項目は、シミュレータウィンドウの下部にあるInformationバーを切り替えます。Informationバーには、現在実行中のアプリケーションの名前、画面サイズ、ピクセル形式が表示されます。
- Viewメニューの0° / 90° / 180° / 270°項目はデバイスシミュレータを回転させます。右上隅にあるRotate buttonもデバイスシミュレータを回転させます。
- シミュレータウィンドウの左上隅にあるDevice pop-upは、シミュレートするデバイスを選択します。
- 右上隅にあるMode buttonは、ライトモードまたはダークモードを選択します。
シミュレータをデバッグに使用する場合、xsbug デバッガーには2つのタブが表示されます。1つはシミュレータで実行中のアプリケーション用、もう1つはデバイスシミュレータ用です。デバイスシミュレータのタブは常に mcsim という名前で、アプリケーションのタブの名前は実行中のプロジェクトによって異なり、balls や helloworld などになります。