SophiaCompress(BREW) EARTH ユーザーズマニュアル : BREW mod ファイル圧縮ツール

SophiaCompress(BREW) EARTH とは

SophiaCompress(BREW) EARTH は、BREW アプリの実行モジュール ( mod ファイル ) を最小化する、世界初の BREW mod ファイル圧縮ツールです。

動作環境

Brew MP 環境	Brew MP SDK 1.0
BREW 環境	BREW SDK 4.0 / 3.1 / 2.1 / 2.0 / 1.1 / 1.0
Windows 環境	Windows 7 / XP
キャリア	KDDI など

圧縮方式

SophiaCompress(BREW) EARTH では、 『ダイレクト圧縮』、 『ファイル分割圧縮』、 『フォーク圧縮』と呼ぶ 3 種類の圧縮方式が利用可能です。

各圧縮方式がサポートする BrewMP / BREW のバージョンや、アプレット、エクステンションは、以下の通りです。

ダイレクト圧縮は、BrewMP 1.0 / BREW 4.0 - 1.0 のアプレットと、 BrewMP 1.0 / BREW 4.0 - 1.0 のエクステンションに対応しています。
ファイル分割圧縮は、 BrewMP 1.0 / BREW 4.0 - 1.0 のアプレットと、 BrewMP 1.0 / BREW 4.0 - 3.1 のエクステンションに対応しています。
フォーク圧縮は、 BrewMP 1.0 / BREW 4.0 - 1.0 のアプレットに対応しています。

各圧縮方式がサポートする BrewMP / BREW のバージョン、アプレット、エクステンション

圧縮方式	BrewMP 1.0 / BREW 4.0 - 1.0 アプレット	BrewMP 1.0 / BREW 4.0 - 3.1 エクステンション	BREW 2.1 - 1.0 エクステンション
ダイレクト圧縮	○	○	○
ファイル分割圧縮	○	○	×
フォーク圧縮	○	×	×

SophiaCompress(BREW) EARTH 圧縮原理

ダイレクト圧縮

ダイレクト圧縮は、圧縮元のモジュールファイル(.mod ファイル)を圧縮して、携帯電話上で実行可能な別のモジュールファイル(.mod ファイル)を生成します。

圧縮率は 60～75 % です。

ダイレクト圧縮

圧縮後は、圧縮後モジュールファイルだけを携帯電話にインストールします。圧縮後モジュールファイルを実行すると、アプリの実行が開始します。

ダイレクト圧縮の場合、実行時に圧縮後モジュールがヒープに常駐するためメモリ消費量もそれだけ増加します。通常、BREW 2.1 - 1.0 のエクステンションでない限り、 ファイル分割圧縮またはフォーク圧縮を利用することを推奨します。

ファイル分割圧縮

ファイル分割圧縮は、圧縮元のモジュールファイル(.mod ファイル)を圧縮して、起動モジュールファイル (.mod ファイル) と圧縮データファイル (.scb ファイル) を生成します。

圧縮率は 60～75 % です。

ファイル分割圧縮

圧縮後は、起動モジュールファイルと圧縮データファイルを携帯電話にインストールします。起動モジュールファイルを実行すると、圧縮データファイルが読み込まれ、アプリの実行が開始します。

※1. 制約事項 : 圧縮対象のファイル名は 127 文字以下でなければいけません。

※2. BREW 1.x/2.x のエクステンションでは、ダイレクト圧縮だけがサポートされます。

※3. ファイルの特権を mif ファイルに設定する必要があります。

Brew MP 1.0 / BREW 4.0 - 3.1 エクステンションのファイル分割圧縮

mif ファイルの設定方法

Brew MP 1.0 | BREW 4.0 - 3.1 エクステンションをファイル分割圧縮する場合、圧縮時にエクステンションのクラス ID を指定する必要があります。

また、エクステンションの mif ファイルの設定では、

　　エクステンション名.scb

について ACL を設定する必要があります。

具体的には、mif ファイルのアクセスコントロールのタブを以下のように設定します。

    Path  ： エクステンション名.scb
    Right ： r (読み取り権限)
    Group ： 0x0 (全員)

この設定により、任意の BREW アプレットまたはエクステンションがファイル分割圧縮されたエクステンションの圧縮モジュールにアクセスできるようになります。

ファイル分割圧縮時の mif ファイルの設定

※1. Brew MP 1.0 | BREW 4.0 / 3.1 エクステンションをファイル分割圧縮する時は、GUI または CUI でクラス ID ( 8 桁の 16 進数)を指定する必要があります。

※2. BREW 1.x / 2.x のエクステンションはファイル分割圧縮できません。ダイレクト圧縮のみサポートされます。

フォーク圧縮

フォーク圧縮は、 ファイル分割圧縮と同様に、圧縮元のモジュールファイル(.mod ファイル)を圧縮して、起動モジュールファイル (.mod ファイル)と圧縮データファイル(.scb ファイル)を生成します。

ファイル分割圧縮と異なるのは、プラグインモジュールファイル(.mod ファイル)が、起動モジュールファイル(.mod ファイル)に埋め込まれる点です。プラグインモジュールは解凍前や解凍後、エラーの発生したときなどに画像やテキストを描画するなど起動画面をカスタマイズできます。

圧縮率は 60～75 % です。

フォーク圧縮

圧縮元のモジュールサイズが大きて、解凍と起動に時間がかかるような場合に有効です。

※1. 制約事項 : 圧縮対象のファイル名は 127 文字以下でなければいけません。

※2. エクステンションには対応していません。

※3. ファイルの特権を mif ファイルに設定する必要があります。

※4. プラグインモジュールは起動モジュールに結合されるため、実機への転送の必要はありません。

ライセンスファイル

SophiaCompress(BREW) EARTHを使用するためには、ライセンスファイル licence.datが必要です。

ライセンスファイルの申請に必要な ホスト ID は、 SophiaCompress(BREW) EARTH のフォルダに同梱されている、 HostID.exe を起動して取得します。

インストール時のSophiaCompress(BREW) EARTH のフォルダ

※デフォルトでインストールした場合、SophiaCompress(BREW) EARTH のフォルダは以下の位置にあります。

製品版 : C:\Program Files\Sophia Cradle\SophiaCompressBREW\6.0
評価版 : C:\Program Files\Sophia Cradle\SophiaCompressBREW Evaluation\6.0

取得したホスト ID を、[コピー] ボタンを押してコピーします。

以下の 5 つの情報を添えて、宛にお申し込みください。

件名：SophiaCompress(BREW) EARTH ライセンスファイル申請


以下の通り、SophiaCompress(BREW) EARTH のライセンスファイルを申請します。

1. ホストID 　 　　:
2. 会社名　　　　　:
3. 担当者名　　　　:
4. 電話番号　　　　:
5. メールアドレス　:(法人のメールアドレス)

FAQ：ライセンスファイルとは何ですか？ / FAQ：ホスト ID とは何ですか？

起動方法

弊社より発行されたライセンスファイル(licence.dat)を、SophiaCompressBrew.exe 実行ファイルと同じフォルダに格納します。

ライセンスファイル(licence.dat)を上記フォルダに格納した上で SophiaCompressBrew.exe をダブルクリックして SophiaCompress(BREW) を起動します。

ライセンスファイル設定時のSophiaCompress(BREW) EARTH のフォルダ

※デフォルトでインストールした場合、SophiaCompressBrew.exe は以下のフォルダにあります。

製品版 : C:\Program Files\Sophia Cradle\SophiaCompressBREW\6.0
評価版 : C:\Program Files\Sophia Cradle\SophiaCompressBREW Evaluation\6.0

操作方法

グラフィカルユーザーインターフェース GUI

SophiaCompress(BREW) EARTH インターフェース

SophiaCompressBrew.exe を起動します。
[圧縮元モジュール] に、圧縮する mod ファイルを指定します。正しく指定すると圧縮前のモジュールサイズが [モジュールサイズ] 欄に表示されます。
[BREW バージョン] を指定します。
[エンディアン] を指定します。(＊日本国内の端末はリトルエンディアンです。)
[最適化] を指定します。圧縮後のモジュールのファイルサイズを優先するか、起動速度を優先するかを選択します。
[圧縮形式] を指定します。ダイレクト圧縮、ファイル分割圧縮、フォーク圧縮の 3 種類の方式を選択できます。
[ファイル拡張子] を指定します。 ファイル分割圧縮またはフォーク圧縮選択時のファイル名の拡張子を指定します。デフォルトは "scb" です。
Brew MP 1.0 | BREW 4.0 / 3.1 エクステンションをファイル分割圧縮する時は、[Extension] をチェックし、クラス ID ( 8桁の 16 進数)を入力します。
[プラグインモジュール] はフォーク圧縮を選んだ時に指定します。起動時に画像やテキストを画面に表示するプラグインモジュールを指定できます。
[圧縮] ボタンを押します。
ファイル保存ダイアログが表示されますので、圧縮ファイルを保存するパスを指定します。
圧縮中は処理中ダイアログが表示されます。
圧縮に成功すると、圧縮後のサイズや圧縮率などの情報を示した履歴ウィンドウが開きます。また、緑色で圧縮後のモジュールサイズが [モジュールサイズ] 欄に表示され、その際の圧縮率が [圧縮率] 欄に表示されます。圧縮後のサイズが圧縮前よりも大きくなった場合は、警告ダイアログと共に赤色でサイズと圧縮率が表示されます。

SophiaCompress(BREW) EARTH アイコンへのドラッグアンドドロップや、圧縮ウィンドウへのドラッグアンドドロップによる圧縮も可能です。

履歴ウィンドウの説明

履歴ウィンドウ

[表示]→[履歴] メニューから履歴ウィンドウを開きます。
左から圧縮元モジュール名、プラグインモジュール名、圧縮前サイズ、圧縮後サイズ、圧縮率、プロパティ(圧縮に使用したオプション)、圧縮日時が表示されます。圧縮後サイズが圧縮前サイズより小さい場合は、緑色の文字、そうでない場合は赤色の文字で、圧縮後サイズと圧縮率が表示されます。
履歴をすべて消去するには、[ファイル]→[履歴を消去] メニューを選択します。

コマンドラインユーザーインターフェース CUI

※ コマンドラインユーザーインターフェースは、Deluxe 版と Enterprise 版でのみ利用可能です。 Standard 版では利用できません。

SophiaCompress(BREW) EARTH コマンドラインの構文は以下の通りです。

SophiaCompressBrew.exe -(direct | file | fork) [-(little | big)] -(brew10 | brew11 | brew2x | brew3x | brew4x | brewmp1x) [-(size | speed)] [-suffix xxx] [-clsid xxxxxxxx] [-plugin yyyyy.mod] [-ov] [-o destination.mod] source.mod

-(direct | file | fork) は圧縮方式を選択します。このオプションは三者択一で省略できません。
-(little | big) は端末の CPU のエンディアンを指定します。省略するとリトルエンディアンとして扱われます。
-(brew10 | brew11 | brew2x | brew3x | brew4x | brewmp1x) は BREW バージョンを指定します。現バージョンでは、-brew4x と -brewmp1x は同じです。両オプションは同じバイナリを生成します。
-(size | speed) は、サイズ優先、もしくは、速度優先の最適化を選択します。このオプションは省略するとサイズ優先として扱われます。
-suffix は、ファイル分割圧縮したファイルの拡張子を指定します。デフォルトでは scb です。(-suffix は -file または -fork を指定したときに有効です)[省略可能]
-clsid は上記のエクステンションのクラス ID を 8 桁の 16 進数で指定します。( -clsid は、-ext と -brew3x | -brew4x | brewmp1x と -file を指定したときに有効です)[省略可能] (※ SophiaCompress(BREW) EARTH 6.0.1 までに存在していた -ext オプションを指定する必要はありません。)
-plugin は、フォーク圧縮方式を選択したときのプラグインモジュールを選択します。フォーク圧縮方式を選択したときは省略できません。
-ov は圧縮後ファイルと同名のファイルがすでに存在するときに強制的に上書きするかどうかを指定します。[省略可能]
-o は圧縮後ファイル名を明示的に指定します。[省略可能]
ここまでのオプションは、指定の順序に制限がありません。
source.mod は圧縮対象ファイルを全てのコマンドライン引数の一番最後に指定します。

※1. source.mod は圧縮元のファイル名、destination.mod は圧縮後のファイル名です。

※2. コマンドラインからの使用においても、圧縮に失敗するなどのエラーが発生した場合には警告ダイアログが表示されます。ただし、GUI からの使用と異なり、圧縮後のファイルサイズが圧縮前よりも大きくなったときに警告ダイアログは表示されません。

ヒープ使用量の増加

ここでは、圧縮方式毎に実行時のヒープ使用量の増加について解説します。

SophiaCompress(BREW) EARTH を使用して圧縮されたモジュールは、実行時は携帯電話のヒープ上に圧縮前と同一のモジュールとして展開されます。

このとき、アプリのモジュール本体以外に起動コード（ブートローダー）もヒープにロードされるので、 SophiaCompress(BREW) EARTH を使用しない場合よりもヒープ使用量は増加します。

※ ダイレクト圧縮では、 起動コードとアプリのモジュール本体の他、圧縮されたモジュールもヒープに常駐するので注意が必要です。通常、BREW 2.1 - 1.0 のエクステンションでない限り、ヒープ使用量増加が起動コードだけで済む、 ファイル分割圧縮またはフォーク圧縮を利用することを推奨します。

ダイレクト圧縮

実行時、起動コード、圧縮後のモジュール、および、 圧縮前のモジュールがヒープに割り当てられます。

圧縮後のモジュールもヒープに割り当てられる点が、他の圧縮方式と異なります。

ダイレクト圧縮:ヒープ使用量

※ 起動コードのサイズは約 3 KB です。

(例) 300 KB の BREW アプリが 100 KB に圧縮された場合、ヒープ使用量の増加は 103 KB です。厳密には、最も近いクラスタサイズの倍数に丸め込まれます。クラスタサイズが 4 KB であれば、正確には 104 KB ということになります。

ファイル分割圧縮

実行時、起動コードと圧縮前のモジュールがヒープに割り当てられます。

ヒープ使用量は、起動コードのサイズだけ増加します。

ファイル分割圧縮:ヒープ使用量

※ 起動コードのサイズは約 3 KB です（実際にはクラスタ単位のサイズ[4, 6, または 8 KB]になります）。

フォーク圧縮

実行時、起動コードと圧縮前のモジュールがヒープに割り当てられます。

ヒープ使用量は、起動コードのサイズだけ増加します。

※起動コードにプラグインモジュールが埋め込まれるため、 プラグインモジュールの内容に応じて起動コードのサイズは変動します。

フォーク圧縮:ヒープ使用量

※ 起動コードの実質的なサイズは約 5 KB + [プラグインモジュールサイズ] です（実際にはクラスタ単位のサイズになります）。

プラグインプロジェクトについて

フォーク圧縮では、 プラグインモジュールを指定する必要があります。

プラグインモジュールを作成するためのサンプルのプラグインプロジェクトが、製品パッケージの plugin フォルダに格納されています。

プラグインプロジェクトのファイル構成

plugin/
  plugin.c              プラグインソースファイル
  plugin.h              プラグインヘッダファイル
  plugin.mod            プラグイン実行モジュール
  plugin_rvctb12.mak    RVCT for BREW 1.2 用メイクファイル
  plugin_rvctb30.mak    RVCT for BREW 3.0 用メイクファイル
  plugin_gnuarm.mak     GNUARM 4.1.1 用メイクファイル
  plugin_yagarto.mak    YAGARTO 4.4.2 用メイクファイル
  elf2mod.x GCC 用リンカスクリプト

plugin.h の内容

plugin.h には、 DrawTypeEnum 列挙型、ForkApplet 構造体、Draw 関数が、以下のように定義または宣言されています。

#ifndef _PLUGIN_H
#define _PLUGIN_H

#include <AEEShell.h>
#include <AEEStdLib.h>

// Draw 関数が呼び出されたタイミングを表す列挙型
enum DrawTypeEnum {
    DRAW_START    = 0, // 展開する直前
    DRAW_LOOP,         // 展開中（現在は未使用）
    DRAW_FINISH,       // 展開した直後
    DRAW_ERROR         // 展開中にエラーが発生したとき
};
// * 現在、DRAW_LOOP は使用できません。 
//   将来の機能拡張のために予約されています。


// 起動モジュールの AEEApplet 構造体
typedef struct ForkApplet   ForkApplet;
struct ForkApplet {
    DECLARE_VTBL(IApplet)
    AEECLSID id;            // [内部使用] アプレットクラス ID
    uint32 reference;       // [内部使用] 参照カウンタ
    IShell* shell;          // IShell ポインタ
    IModule* module;        // [内部使用] IModule ポインタ
    IDisplay* display;      // IDisplay ポインタ
    AEEHelperFuncs* helper; // ヘルパー関数ポインタ
    int32 size;             // ForkApplet 構造体のサイズ
    int32 status;           // [内部使用] ステータス
    int32 error;            // 描画時エラー
    int32 progress;         // 将来の機能拡張のために予約: 現在は常に -1
    void* userdata;         // ヒープに割り当てた開発者独自のデータ領域へのポインタ
    void* reserved;         // 将来の機能拡張のために予約: 現在は常に NULL
};
// 開発者がヒープに割り当てた独自のデータ領域へのポインタは userdata 変数に格納します。
// このデータ領域は、開発者が解放しなければなりません。

void Draw(ForkApplet* applet, int32 draw_type);

#endif//_PLUGIN_H

DrawTypeEnum 列挙型: いつ描画関数が呼び出されるかを表す
ForkApplet 構造体: 起動モジュールの AEEApplet 構造体
Draw 関数: プラグインのエントリポイント。この関数は、ForkApplet 構造体へのポインタと DrawTypeEnum 列挙型の値を引数に持ち、列挙型の値に応じて画像やテキストの描画を行います。

※注意 1 id や、reference、module、status などの内部使用変数の値は変更しないでください。予期せぬ動作を引き起こす可能性があります。

※注意 2 プラグインモジュール内では、グローバル変数を使用できません。

※注意 3 開発者定義のデータとして、ヒープからメモリ領域を確保し、 userdata 変数にそのポインタを格納して利用することが可能です。この場合、確保したメモリ領域は開発者自身が解放しなければいけません。

plugin.c の内容

plugin.c では、サンプルの Draw 関数が以下のように実装されています。

#include "plugin.h"

void Draw(ForkApplet* applet, int32 draw_type)
{
    static AECHAR const     szText[] = {
        'L', 'o', 'a', 'd', 'i', 'n', 'g', '.', '.', '.', '\0'
    };

    applet->helper->dbgprintf(">> Draw: %d", draw_type);

    switch (draw_type) {
        case DRAW_START:
            IDISPLAY_DrawText(applet->display,
                AEE_FONT_BOLD,
                szText,
                -1,
                0,
                0,
                NULL,
                IDF_ALIGN_CENTER | IDF_ALIGN_MIDDLE
            );
            IDISPLAY_UpdateEx(applet->display, FALSE);
            applet->error = SUCCESS;
            break;
        case DRAW_ERROR:
            break;
        case DRAW_LOOP:
        case DRAW_FINISH:
        default:
            break;
    }

    applet->helper->dbgprintf("<< Draw: %d", draw_type);

    return;
}

このサンプルでは、展開する直前に "Loading..." という文字列を画面中央に描画します。描画処理は ForkApplet 構造体の display 変数を使用して行います。描画処理が正常に終了すれば、ForkApplet 構造体の error 変数に SUCCESS を代入します。

Draw 関数内では BREW ヘルパー関数のマクロを使用することができません。その代わり、 BREW ヘルパー関数へのポインタである ForkApplet 構造体の helper 変数経由で BREW ヘルパー関数を呼び出すことが可能です。このとき、通常、ヘルパー関数の名前は小文字になります。

例えば、上記サンプルでは DBGPRINTF マクロを使用せずに、 applet->helper->dbgprintf 関数を使用してデバッグ文字列を出力しています。

プロジェクトのビルド

ビルドを実行するには、Microsoft Visual Studio のメイクツール nmake がインストールし、 BREW SDK やコンパイラ、Elf2Mod ツールのパスを表す環境変数を設定する必要があります。

コンパイラ毎に用意したメイクファイルで使用している環境変数は以下の通りです。

[共通の環境変数: どの実機用コンパイラを使用する場合でも必要とされる環境変数]
BREWDIR                  BREW SDK フォルダのパス

[RVCT for BREW 1.2 の環境変数]
ARMHOME                  RVCT for BREW 1.2 のホームフォルダのパス

[RVCT for BREW 3.0 の環境変数]
ARMBIN                   RVCT for BREW 3.0 の bin フォルダのパス
ARMINC                   RVCT for BREW 3.0 の include フォルダのパス
ARMLIB                   RVCT for BREW 3.0 の library フォルダのパス
ELF2MOD_TOOL_PATH BREW   Elf2Mod ツールの bin フォルダのパス

[GNUARM 4.1.1 の環境変数]
GNUARM41HOME             GNUARM 4.1.1 のホームフォルダのパス
ELF2MOD_TOOL_PATH BREW   Elf2Mod ツールの bin フォルダのパス

[YAGARTO 4.4.2 の環境変数]
YAGARTO44HOME            YAGRTO 4.4.2 のホームフォルダのパス
ELF2MOD_TOOL_PATH        BREW Elf2Mod ツールの bin フォルダのパス

*注意* RVCT for BREW 3.0 / GNUARM 4.1.1 / YAGARTO 4.4.2 では、 QUALCOMM 社のウェブサイトから入手可能な BREW Elf2Mod 1.0.2 が必要です。 BREW Elf2Mod を入手するには、Brew ディベロッパーに認定される必要があります。

メイク

プラグインモジュールを生成するには、以下のコマンドを実行します。

nmake /f plugin_xxxxx.mak

plugin_xxxxx.mak は、インストールされている実機用コンパイラによって以下のように異なります。

plugin_rvctb12.mak (RVCT for BREW 1.2 の場合)
plugin_rvctb30.mak (RVCT for BREW 3.0 の場合)
plugin_gnuarm.mak (GNUARM 4.1.1 の場合)
plugin_yagarto.mak (YAGARTO 4.4.2 の場合)

サンプルではメイクの実行により plugin.mod ファイルが生成されます。このファイルがフォーク圧縮の際に指定するプラグインモジュールです。

制約条件

Brew MP SDK / BREW SDK 標準の起動コードを使用してください。

Brew MP 1.0 | BREW SDK 4.0 / 3.1 / 2.1 / 2.0 / 1.1 / 1.0 に付属の標準の起動コード AEEModGen.c を使用してビルドされたモジュールの圧縮についてのみ、本ソフトウェアはサポートします。

上記以外のカスタマイズされた起動コードを使用している場合、本ソフトウェアにより圧縮されたモジュールは正常に動作しない可能性があります。

BREW C++ ライブラリ & GUI フレームワーク & XML ミドルウェア / 携帯 Java アプリ圧縮ツール : 株式会社 ソフィア・クレイドル

SophiaCompress(BREW) EARTH とは

動作環境

圧縮方式

各圧縮方式がサポートする BrewMP / BREW のバージョン、アプレット、エクステンション

ダイレクト圧縮

ファイル分割圧縮

Brew MP 1.0 / BREW 4.0 - 3.1 エクステンションのファイル分割圧縮

mif ファイルの設定方法

フォーク圧縮

ライセンス ファイル

起動方法

操作方法

グラフィカルユーザーインターフェース GUI

履歴ウィンドウの説明

コマンドラインユーザーインターフェース CUI

ヒープ使用量の増加

ダイレクト圧縮

ファイル分割圧縮

フォーク圧縮

プラグインプロジェクトについて

プラグインプロジェクトのファイル構成

plugin.h の内容

plugin.c の内容

プロジェクトのビルド

メイク

制約条件

Brew MP SDK / BREW SDK 標準の起動コードを使用してください。

BREW C++ ライブラリ & GUI フレームワーク & XML ミドルウェア / 携帯 Java アプリ圧縮ツール : 株式会社ソフィア・クレイドル

ライセンスファイル