本ガイドでは、高度な利用者を対象とする Sencha Cmd の機能を説明します。
前提条件
先に進む前に以下のガイドをご覧になることをお勧めします。
Sencha Cmd について - Sencha Cmd の使用
インストール時の注意
インストール場所
インストーラを実行時にインストール先を選択できますが、変更した場合、その他の設定に影響を及ぼす可能性があります(「複数のインストールバージョン」を参照してください)。すべてのバージョンのSencha Cmdが単一の親フォルダ内にインストールされ、その中にバージョン番号別に名前をつけたサブフォルダが含まれていることが理想的です。Windows上で単一ユーザーにインストールした場合、デフォルトのインストールフォルダは次のようになっています:
C:\Users\myself\bin\Sencha\Cmd\n.n.n.n\
このパスを変更する場合、バージョン番号のフォルダはそのままにして、同じ親フォルダにその他のバージョンのSencha Cmdをインストールしてください。
複数のインストールバージョン
コマンドプロンプトでsencha
を呼び出すと、すべて直前にインストールしたバージョンのSencha Cmdに向かいます。場合によっては、このバージョンは現在作業中のアプリケーションと互換性がないことがあります。
そのような場合に備えて、Sencha Cmdはアプリケーションが使用するフレームワークの指定に応じて必要なバージョンを参照します。そして、そのコマンドを適切なバージョンのSencha Cmdにデリゲートします。
重要この機能が適切に機能するためには、それぞれのバージョンがそれぞれのバージョン番号の名前のフォルダにインストールされ、共通の親フォルダの中に含まれていることが必要です。
あるいは、それぞれのインストールバージョンがSencha Cmdのバージョン特定名も提供します。これは、以下のように実行します:
sencha-x.y.z ....
また、インストーラは、SENCHA_CMD_x_y_z
の書式の環境変数も設定します。この環境変数は、次のように現在のコンソール/シェルの PATH を調整するために使用できます。
Windows上では、このようになります(nは現在のバージョン):
set PATH=%SENCHA_CMD_x_y_z%;%PATH%
sencha ....
OSX/Linux上では、このようになります:
set PATH=$SENCHA_CMD_x_y_z:$PATH
sencha ....
設定
コマンドライン上でSencha Cmdに渡すことができるパラメータはすべて、以下に説明する設定ファイルの1つで設定オプションとして設定できます。コマンドラインオプションが分かっている場合は、そのオプションを設定ファイルに追加するだけです。
例えば、sencha compile
の ignore
パラメーターを設定に指定するには、この行を追加します:
sencha.compile#ignore=attic
この特定の設定は、その実践を勧めるものではなく、構文を示しているだけです。#
より前のコマンド部分がSencha Cmdコマンドで、ドットで区切られています。#
の後の部分がオプション名です。
グローバルオプション(debug
ログなど)を設定するには、このように実行します:
sencha#debug=true
設定は、Sencha Cmd(特にコンパイラ)が複雑になるにつれてさらに重要になります。
現在の設定プロパティを参照するには、このコマンドを実行します。
sencha diag show
設定ファイル
Apache Ant(ほとんどのSencha Cmdの基本)と同様に、設定は「書き込み順」モデルで適用されます。これは、コマンドラインでプロパティ値をオーバーライドできるようにするためには不可欠です。
設定をロードするプロセスは、現在のディレクトリの検索から開始し、ワークスペースが検出されるまでファイルシステムを上方へ進みます。その際、Sencha Cmdは、アプリケーションまたはSencha Framework SDKを検索します。ロードプロセスの最後に、Sencha Cmdは、以下の検出ファイルをこの順にロードします:
${app.dir}/app.json
- 一番具体的なアプリケーションフォルダにある場合、Application 設定が最初にロードします。${app.dir}/.sencha/app/sencha.cfg
- 一番具体的なアプリケーションフォルダにある場合、Application 設定が最初にロードします。${package.dir}/package.json
- 一番具体的なパッケージフォルダにある場合、Package 設定が次にロードします。${package.dir}/.sencha/package/sencha.cfg
- 一番具体的なパッケージフォルダにある場合、Package 設定が次にロードします。${workspace.dir}/workspace.json
- ワークスペース(またはワークスペース内のアプリやパッケージ)で作業中の場合、Workspace 設定が次に適用されます。${workspace.dir}/.sencha/workspace/sencha.cfg
- ワークスペース(またはワークスペース内のアプリやパッケージ)で作業中の場合、Workspace設定が次に適用されます。${framework.dir}/cmd/sencha.cfg
- 現在のディレクトリのアプリやパッケージに適用できるフレームワークに基づき、そのプロファイルが次にロードします。${home.dir}/.sencha/cmd/sencha.cfg
- 個人用の設定が次にロードします。これは一般に上位のプロパティだけを設定します。${cmd.dir}/../sencha.cfg
- ローカルマシン Sencha Cmd の設定が次にロードします。これは一般に上位のプロパティだけを設定します。稼働中のSencha Cmdの親フォルダからロードします。この親フォルダにはさまざまなインストールバージョンのSencha Cmdが保存されています。${cmd.dir}/sencha.cfg
- 最後に、Sencha Cmdのバージョン固有の設定がロードします。
コマンドラインで渡される設定プロパティが最も重要です。これらは上記のファイルのいずれかからのプロパティをオーバーライドします。例:
sencha config -prop foo=42 then ...
設定ファイルをロードする前に、"foo"
を 42 に設定します。Sencha Cmd v3.1 以降では、この設定は “wins” です。
ほとんどの場合、プレフィックスからプロパティの出所がわかります。
app.
–"app.json"
および".sencha/app/sencha.cfg"
を参照してください。package.
–"package.json"
および".sencha/package/sencha.cfg"
を参照してください。workspace.
–"workspace.json"
および".sencha/workspace/sencha.cfg"
を参照してください。framework.
– Sencha Touch SDK まはた Ext JS の"cmd/sencha.cfg"
を参照してください。cmd.
– Sencha Cmd インストールフォルダの"sencha.cfg"
を参照してください。
これらのプロパティはこれらのファイルに設定される必要はありませんが、これはデフォルトで、この規則に従うと設定の管理に役立ちます。しかしながら、アプリケーションによってワークスペース設定をオーバーライドすることが必要な場合もあります。このためには、workspace.foo
プロパティが、アプリケーションレベルの設定ファイル、".sencha/app/sencha.cfg"
に設定されていることが必要です。規則に従わない場合、コメントを残しておくことを推奨します。
JSON 記述子の使用
Sencha Cmd v5 では、JSON ファイルが対応する "sencha.cfg"
ファイルよりも常に優先されるようになりました。以前のリリースでは、これは Sencha Touch ベースのアプリケーションのみに適用されていました。
"app.json"
、"package.json"
、"workspace.json"
などのファイルのコンテンツはファイル名プレフィックスが適用されてプロパティ("app"
、"package"
、"workspace"
)に結合されています。例えば、以下の JSON オブジェクトを "workspace.json"
に配置した場合:
{
foo: {
bar: 42
}
}
workspace.foo.bar
プロパティを値 “42” に設定します。
このメカニズムによって、ビルドプロセスで使用するために app.id
プロパティを "app.json"
からインポートできます。
Javaシステムプロパティ
Javaシステムプロパティは、HTTPプロキシサーバー設定など、Sencha Cmdで設定することが必要な場合があります。Cmdをインストールしたフォルダ内の"sencha.cfg"
ファイルには、システム定義プロキシの検出を可能にするプロキシのデフォルト設定があります。詳細は、"${cmd.dir}/sencha.cfg"
に記載されているコメントを参照してください。
注意:これらの設定を変更する必要がある場合、Cmdをアップグレードしてもこの設定が保存されるように、"${cmd.dir}/../sencha.cfg"
ファイルを使用してください。
これらのプロパティは、sencha upgrade
を実行、またはパッケージをダウンロードするために、ウェブにアクセスするSencha Cmdの能力に影響を与えます。これらのオプションはCmd v3.1.1以降のオプションです。
コマンドライン詳細
Sencha Cmdを頻繁に利用する場合、以下のヒントが役立ちます。
最も短い一意の接頭辞
Sencha Cmdのコマンド、カテゴリ、オプションはすべて正式名または固有の最短接頭辞によって指定できます。
例をあげると、Sencha Cmdの中でgenerate
は現在、文字「g」から始まる唯一の最上位カテゴリ、同様に、app
は「a」から始まるカテゴリの唯一のコマンドであるため、以下のコマンドに等しくなります:
sencha generate app MyApp ../MyApp
sencha gen ap MyApp ../MyApp
重要これはコンソールまたは端末で便利な場合がありますが、過度に短縮/簡略形式の接頭辞をスクリプトで使用することは優れた実施基準とは言えません。スクリプト内で簡略したコマンドを使用すると、スクリプトの理解や保守が困難になり、新しいコマンドによってこの短縮形が曖昧になった場合、エラーになる可能性があります。
コマンドチェーン
Sencha Cmdのコマンドラインプロセッサは、すべてがディスパッチされるまで、与えられたコマンドをすべて実行します。つまり、複数のコマンドを実行するために、Sencha Cmdプロセスを再起動するコストを回避できます。これを利用するには、コマンドの間にand
またはthen
を挿入します。
and
やthen
コマンドは、Sencha Cmdの実行モデル、およびコマンドやカテゴリの階層構造を基本とします。and
コマンドは、前のコマンドと同じカテゴリの別のコマンドを実行するために使用します。これは最も一般的な使用例です。
例えば、コントローラと2つのモデルを生成するには、このように使用します:
cd /path/to/MyApp
sencha generate controller Central and model User id:int and model Ticket id,name,email
上記の例では、and
を2回使用したために、generate model
コマンドが2回実行されています。then
コマンドはand
と同様ですが、次のコマンドがルートカテゴリ(つまり、sencha
コマンド)の一部である点が異なります。
例えば、以下の例では、新しいモデルを生成してから、アプリケーションをビルドします:
cd /path/to/MyApp
sencha generate model User id:int,name then app build
レスポンスファイル
コマンドチェーンが開始して、例えば複雑なビルドスクリプトなどでコマンドラインが長すぎて読み取り不可能になる場合、ファイルにコマンドライン引数を入力して、そのファイルから引数を読み取るようにSencha Cmdに命令できます。
例えば、
cd /path/to/MyApp
sencha @file.sencha
上記の例では、"file.sencha"
ファイルが読み込まれ、各行がコマンドライン引数になります。ただし、ラインの先頭が「#」から開始している場合はスキップされます。指定したファイルのすべての行は、"@file.sencha"
ではなく、コマンドラインに入力したかのように、コマンドライン引数に挿入されます。つまり、"file.sencha"
はレスポンスファイルの挿入も含むことができます(例えば、"@file2.sencha"
)。
カテゴリの状態
性能を向上するために、カテゴリの中には、複数回実行されたコマンド全体の状態を維持するものがあります。最適な例は、新しいcompile
カテゴリのコマンドです。各コマンドのソースをすべて読み込むのではなく、compile
カテゴリは、クラスパスのファイルすべてのキャッシュを維持します。その後、このコンテキストは、そのカテゴリのコマンドすべてに公開されます。
以下のコマンドは、ext-all-dev.js
ファイルとext-all.js
ファイルを再ビルドしますがフレームワークソースは1回しか読み込みません:
cd /path/to/MyApp
sencha compile -c sdk/src --debug=true concat -o sdk/ext-all-dev.js \
and --debug=false concat -c -o sdk/ext-all.js
このキャッシュを使用したくない場合、例えば、ファイルセットが次のセットの出力と同じではない場合は、以下のようにthen
コマンドを使用します。
cd /path/to/MyApp
sencha compile -c sdk/src --debug=true concat -o sdk/ext-all-dev.js \
then compile -c app/foo --debug=true concat -o app/foo/foo-all.js
現在、コマンド全体の状態を維持するのは、compile
カテゴリだけです。
プラグイン
同じSencha CmdのインストールがExt JSとSencha Touch両方で使用されますが、フレームワークに応じて、コマンドがやや異なる動作を実行する場合が多々あります。さらに、コマンドの中には、1つのフレームワークでしか使用できない場合もあります。
これに対応するため、Sencha Cmdの機能は、コマンドライン(正式名は「Sencha Cmd)」とAntで使用される下位インターフェイスという2層にまたがってパーティションされています。これらの特別な考慮を必要とするコマンドは、コマンドラインからプラグインへ送られます。
Sencha Cmdプラグインは、"plugin.xml"
というファイルに含まれたAntスクリプトに過ぎませんが、コマンドによっては、アプリケーションまたはワークスペースで実行された場合、複数の有効なプラグインが存在する可能性があります。
このプロセスは、以下のような最も特定の利用可能なプラグインを検索することから開始します。
${app.dir}/.sencha/app/plugin.xml
${workspace.dir}/.sencha/workspace/plugin.xml
${cmd.dir}/plugins/${framework.name}/${framework.plugin.version}/plugin.xml
${cmd.dir}/plugin.xml (「デフォルトプラグイン」とも呼ばれます)
これらのうち、最初に検出されるのは、現在のディレクトリにあるものです。次に、Sencha Cmdは、そのプラグインだけをロードし、与えられたコマンドに基づいて特定のターゲットを起動します。ただし、これらのプラグインは、そのすぐ上のレベルでプラグインをロードするために必要なAntインボケーションを含んでいます。例えば、アプリケーションプラグインが検出された場合、ワークスペースプラグインのimport
が含まれています。そのプラグインは、フレームワークプラグインのimport
を含み、したがって、デフォルトプラグインのimport
が含まれています。
拡張ポイント
厳密には、最下位の2つのレベル(フレームワークとデフォルトプラグイン)だけが、実際のコードを含むプラグインです。アプリケーションプラグインとワークスペースプラグインは、デフォルトで空ですが、これらのビルトインコマンドのユーザー拡張を可能にするために用意されています。これは、Sencha Cmdに行われたコード生成リクエストのプロジェクトまたはアプリケーション基準を強制実施するロジックを追加できるようにするためです。
例えば、新しいモデル定義がプロジェクトのガイドラインを守っているか確認することが必要な場合、最初のフィールドは必ずid:string
で、これをアプリケーションまたはワークスペースの"plugins.xml"
に追加します。
<target name="-before-generate-model">
<if>
<not><matches string="${args.fields}" pattern="^id\:string,.*"/></not>
<then>
<fail>Models must have "id:string" as first field.</fail>
</then>
</if>
</target>
同様に、新しいモデルが追加された際にその他のシステムを更新するフックを提供することもできます。
<target name="-after-generate-model">
... post new/updated Model ${args.name} and ${args.fields} ...
</target>
実際のターゲット名は、拡張するプラグインによって異なります。詳細については、それぞれの"plugin.xml"
ファイルのコメントを参照してください。
注意:デフォルトの"plugin.xml"
ファイルは、有用なタスクを多数提供するAnt Contribをインポートします。
Antでの使用
Sencha Cmdは主にコマンドラインで(したがって、その名前を)使用しますが、Antから直接使用することも可能です。このレベルで提供される多数のコマンドについての詳細は、Antインテグレーションガイドを参照してください。