Gaia 構造入門書

この記事ではGaiaのビルドシステムがどのように動作するのかを、makefileや、ビルド手順や、環境変数や、カスタマイズを含めて説明します。

ビルドステップ用に意味のある成果の大半は、Gaiaの build/ サブディレクトリにあるスクリプトによって実行されます。これはmakeやnode.jsや、XULRunnerの実行環境である XPCShell (JS Shellとも言う)を使って実行されます。Gaiaのビルドシステムは、webアプリのインストールや、テストや、ローカライゼイションや、実端末へパッケージするのに役立つヘルパーツールを含んでいます。その他に開発者がGaiaをカスタマイズするのも可能になり、例えば、デフォルトの壁紙、着信音、アプリ、設定の変更ができます。

記: XPCShell は node.js と同様ですが、違いとしていくつかMozilla風味の javascriptも実行できます。これは Gaia ビルドスクリプトを Firefox拡張機能内で実行できるようにします。

Makefile

Makefileはひとかたまりのゴールから構成されています。この節では最も役立つものを説明します。

install-gaia

このゴールは全てのGaia用アプリを端末にプッシュします。特定のアプリだけをプッシュしたい場合、次のように APP フラグを使用できます:

APP=calendar make install-gaia

このディレクトリは Gaia アプリのディレクトリ(例 apps)の中にある必要があります。

reset-gaia

これは install-gaia とほぼ同じ動きをしますが、違いはまず掃除(clean)をして、次に全アプリをインストールした後にパーミッションをセットアップします。アプリはエンジニアリングビルドと同様に /data/local 内にあります。これはテストやデバッグのアプリもプッシュします。

要注意: APP 環境変数を reset-gaia と一緒に使うと動作しているように見えますが、電話機が使えない状態 (このゴールを APP 変数なしで実行すると復活できます) になるでしょう。なので行わないようにして下さい。

production

reset-gaia と同様で、違いはソースコードが最適化されます。このゴールは基本的にユーザビルドのエミュレーションを可能にします。これはユーザビルドでインストールされるアプリもプッシュされます。

要注意: APP 環境変数を production と一緒に使うと動作しているように見えますが、電話機が使えない状態 (このゴールを APP 変数なしで実行すると復活できます) になるでしょう。なので行わないようにして下さい。

reference workloads

このゴールは端末に色々なサイズの負荷をかけて、デバッグしたり、パフォーマンスや、起こりうるスケーラビリティの問題を修正したりするのに役立ちます。このゴールは APP または APPS 環境変数を受け入れ、それはスペースで区切られたアプリ名を含みます、例えば

APP=sms make reference-workload-light
APPS="sms communications/contacts" make reference-workload-heavy

記: 詳細情報は、Hacking Gaia: Reference workloadsを読んで下さい。

環境変数

いくつかの環境変数は端末へのビルドとインストールの側面を制御します、例えば:

P=1

これはマルチコアCPUを活かしてビルド時間を高速化するパラレルビルドを有効にします。デフォルト値は 0です。

要注意: パラレルビルドは実験的機能で、不安定な場合があります。

GAIA_OPTIMIZE=1

これは JavaScript ファイルの最適化を有効にします。これは make production 実行時に自動的にセットされます。これは install-gaia や reset-gaia でも使われることがあります。

PRODUCTION=1

これは基本的に make production のエイリアスです。

DEBUG=1

これは Gaia ユニットテストや、FirefoxでFirefox OSアプリを開発する時に使う、デバッグプロファイルを生成できるようになります。新規生成の前に、既存のプロファイルディレクトリを削除しておく必要があります。

DEVICE_DEBUG=1

端末の画面ロックを無効にします。

GAIA_DEVICE_TYPE=phone

この変数は色々な 'app.list' から特定端末をビルドするのを許可します。全ての 'app.list' ファイルは /build/config/$(GAIA_DEVICE_TYPE)/ フォルダにあります。

GAIA_DEVICE_TYPE のデフォルト値は phone です。

記: 詳細とオプションについては、Hacking Gaia make options のガイドを参照下さい。

ビルド手順

ここにgaiaをビルドするためのシーケンス図があります:

pre-app.js と app.js と post-app.js とは Makefile によって実行され、大抵のビルドタスクは xpcshell スクリプトによって完了します。Makefile はOSを判定したり b2g-desktop をダウンロードするのに使われ、我々はMakefile から xpcshell スクリプトにタスクを移行する予定です。

なぜ pre-app と app と post-app とがあるのか疑問に思うかもしれません、それは Makefile から xpcshell スクリプトへ、依存性を移動しているからです、なので大半の依存性を xpcshell に移行するため、 pre-app.js と post-app.js を bug 1021051 に基いて作りました。そして最終的には、bug 1053703 に基いてapp.js と pre-app.js と post-app.js はマージされるでしょう。

gaiaビルドシステムには3種類のディレクトリがあります:

ソースディレクトリ: apps, dev_apps, shared ディレクトリ
ステージディレクトリ: build_stage
プロファイルディレクトリ: profile, profile-debug や profile-test ディレクトリ

我々のゴールはソースディレクトリにファイル生成することでは決してなく、不幸にもまだソースディレクトリにファイル生成するモジュールが残っていますが、この問題を解決する予定です。どのモジュールがソース、ステージ、プロファイルディレクトリにファイル生成するのかを示す表がここにあります。

ここにgaiaディレクトリで make が実行された時のビルドプロセスを、実行される順に載せます:

b2g_sdk: b2g-デスクトップは GAIA_DIR/build/にある xpcshell スクリプトを実行するのに使われます。
svoperapps: モバイル通信事業者や国がインストールするアプリ用に、アプリをダウンロードして、設定ファイルを生成します。
webapp-manifests: ビルドプロセス用のwebアプリのメタデータを生成します。
keyboard-layouts: デフォルトのキーボードレイアウト設定を生成します。
settings.json (settings.js): この JavaScript はFirefox OSのデフォルト設定を生成し、それは Gaia により読み込まれます。
webapp-shared: 各アプリに使われるファイルを、shared ディレクトリから build_stage ディレクトリに移動します。
preferences: Firefox OS用のデフォルト設定を生成します; user.js ファイルを生成して端末に配置し、Geckoにより読み込まれます。この値は DEBUG=1 のような別の環境変数によって変更される可能性があるのに注意して下さい。
app.js: アプリディレクトリ内のMakefile: これらが存在する場合に実行されます。各アプリにとって、アプリのMakefileがなければ、Gaia Makefile がアプリのディレクトリをbuild_stageにコピーして、[アプリディレクトリ]/build/build.js があれば実行します。より詳細は Build script for apps を見て下さい。
test-agent-bootstrap & test-agent-config: 2つのmakeルールを含む test-agent をセットアップします、test-agent-config と test-agent-bootstrap-apps で、これは各アプリのテスト環境セットアップに使われます。
webapp-optimize: このスクリプトはJavaScript 最小化、ローカライゼーションリソースファイルを JSON ファイルにまとめる、必要に応じてデフォルト言語用の HTML ファイルを生成する、といった色々な最適化手順を含みます。
webapp-zip: これは各アプリを別のzipファイルに圧縮して profile/ ディレクトリに配置します。
optimize-clean: optimize-clean はデフォルト言語のHTMLファイルをきれいにします。
contacts: GAIA_DISTRIBUTION_DIR に存在すれば、事前読込された連絡先ファイルをプロファイルにコピーします
extensions: GAIA_DIR/tools/extensions 内の拡張機能をプロファイルディレクトリにコピーします; 別の設定のセットアップは別の拡張機能のコピー指定を可能にします。
installed-extensions.json (additional-extensions.js): 最終的に、このスクリプトが追加拡張機能をプロファイルディレクトリにダウンロードします。

アプリ用のビルドスクリプト

デフォルトでは、アプリのビルドスクリプト [アプリディレクトリ]/build/build.js がある場合、app.js によって実行されます。$APP/build/build.js がない場合、app.js はアプリを build_stage にコピーします。

アプリディレクトリ内のファイルは、アプリのビルドスクリプトによってbuild_stage ディレクトリにコピーされるべきです、なぜなら app.js はアプリのビルドスクリプトがある場合はそれらをコピーしないからです。例えばカレンダーアプリに build/build.js があって、カレンダーアプリ用の build.js によってutils.copyToStage() が呼ばれるべきです。

記: アプリケーション外部のソース (shared/ の中のような) のために、index.html の<head> 内のコメントの中に入れておく必要があって、それにより、shared/ がアプリ内にコピーされるようになります。

アプリ用のビルドスクリプトは $GAIA_DIR/build 内の全ビルドモジュールが必要で、特にアプリのビルドに便利なユーティリティモジュールが要ります。モジュールを取得するのに require('utils') を使えます。

設定をカスタマイズする

カスタム設定があると気づいた場合、端末に書き込む時間をそれぞれセットする必要があり、custom-prefs.js というファイルをbuild/config ディレクトリ内に作ってその中におく事ができます。これで上書きされてソース制御外になるのを防止できます。

ここに便利な設定があります:

// this enables marionette which lets you run performance tests
// see https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Platform/Testing/Gaia_performance_tests
user_pref("marionette.defaultPrefs.enabled", true);

// this sets the port for remote debugging your application on the device
user_pref("devtools.debugger.remote-port", 60000);

// this enables the remote debugger
user_pref("devtools.debugger.remote-enabled", true);

// this outputs debug information about the Radio Interface Layer in logcat
user_pref("ril.debugging.enabled", true);

このファイルはプロファイル生成するたびに読み込まれます。全て確実に生成させるのに最も安全な方法は、最初にプロファイルを消す事です:

rm -rf profile && make profile

それで install-gaia ゴールを安全に使えます。

FAQ

焼き込み後に端末が黒いままになる

これは端末がアイドル時に焼き込みした場合に時々起こりえます。これを治療するには単にコマンドラインで次のコマンドを使って B2G を再起動します:

adb shell stop b2g && adb shell start b2g