Sencha Cmd はクロスプラットフォームのコマンドラインツールです。Sencha Cmd はバックグラウンドで Apache Ant を使用してその機能の大半を提供しています。本ガイドは Sencha Cmd へのこのインターフェイスの最も重要な機能について説明します。
前提条件
先に進む前に以下のガイドをご覧になることをお勧めします。
Ant
Apache Antは長期にわたりJava開発コミュニティにおいて中核的な役割を担ってきましたが、Antは根本的にはクロスプラットフォーム スクリプトを記述するXMLベースのプラットフォームです。「言語」ではなく「プラットフォーム」と呼んでいるのは、Ant を使用するとコードのライブラリを JAR 形式で簡単に組み込むことができ、また Ant スクリプトの一部として使用できるスクリプト言語が多数サポートされているためです。
当然ながら、AntからSencha Cmdのような別のプログラムを呼び出し、引数を渡し、終了コードを処理できますが、Antが最も得意しているのはファイル操作です。これは、Ant がビルドスクリプトで使用できるように設計されているためです。
Advanced Sencha Cmdガイドで触れたとおり、Sencha CmdはJARファイルとして提供され、その中核的な機能はAntライブラリ(antlib
)として公開されます。Sencha CmdのコマンドラインレベルもSDK固有の処理と共にこのレイヤーの上に実装されます。したがって、一方で可能なことはもう一方においても可能です。
Antを使用している場合、Sencha Cmdの使用は、コマンドラインインターフェイスを使用して繰り返し呼び出すよりも、このレベルで行うほうが良いでしょう。
<taskdef resource="com/sencha/ant/antlib.xml"
classpath="${cmd.dir}/sencha.jar"/>
Antスクリプトでsencha ant ...
を使用した実行処理を行う場合、cmd.dir
プロパティでエントリを定義します。これを行わない場合、Antスクリプトや実行者がローカルコンピューターに対してcmd.dir
を適切な方法で指定することが必要です。
x-sencha-init
このタスクでは、現在のディレクトリにしたがって"sencha.cfg"
ファイルから設定プロパティをロードします。この処理は一般に、Sencha Cmdが必要な、Senchaアプリケーションのビルドに固有のAntスクリプトによって行われます。
<x-sencha-init/>
また、これにより、使用可能なSencha Cmdの拡張機能(x-compass-compile
など)で定義されたタスクすべてがロードされます。
x-sencha-command
このコマンドは、コマンドラインインターフェイスに相当するものです。引数はこのタグの本文テキストに記述され、1行が1つの引数となります。両端の空白は除去されるため、インデントレベルはそれほど大きくはなりません。インデントはコマンドラインの構造を明確にするために使用すると良いでしょう。次に例を示します。
<x-sencha-command>
compile
--classpath=app,sdk/src
page
--in=app/index.html
--out=build/index.html
</x-sencha-command>
各行が引数となるため、空白は特殊なものではありませんので、エスケープしたり引用符をつけたりしないでください。
Antプロパティは拡張されているので、次のようなかなり慣習的なスタイルでも可能です。
<x-sencha-command>
compile
--classpath=${app.dir},${sdk.dir}/src
page
--in=${app.dir}/index.html
--out=${build.dir}/index.html
</x-sencha-command>
コメントがサポートされるようになったため、コマンドの説明を記述したり、一部の記述を削除したりすることなく一時的に保留状態にしておくことができます。また、空白行はスキップされます。
<x-sencha-command>
compile
#appフォルダおよびsdk/srcフォルダをインクルードする
--classpath=${app.dir},${sdk.dir}/src
# Turn off debugging (comment next line to leave debug enabled):
# --debug=false
page
#アプリケーションのメインページ:
--in=${app.dir}/index.html
# The compiled page goes in build folder along with "all-classes.js":
--out=${build.dir}/index.html
</x-sencha-command>
x-extend-classpath
このタスクでは、現在のClassLoaderのclasspathを拡張します。これは多くの場合"sencha.jar"
をclasspathに取り込む際に必要となりますが、Antスクリプトを起動する際に動的にclasspathを拡張することが必要な場合にも役立ちます。
必要な数のJARをリスト化することができます。
x-generate
このタスクでは、次の2つの基本的なモードでテンプレートからの出力を行います:file
およびdir
。したがって、テンプレートジェネレーターにはソースファイルを単体で渡すことも、ソースフォルダごと渡すこともできます。
テンプレート
ソースファイルの名前によって、テンプレートとして処理されるものかどうかを判定します。
.tpl
= Ext.XTemplate
たとえば、"foo.js.tpl"
がXTemplateエンジンを使用した"foo.js"
の生成に使用されます。
ファイルのマージ
ファイルを生成時の内容から変更する必要が生じる可能性がある場合(ターゲットを再生成するなど)に".merge"
サフィックスを使用すると便利です。主な使用例として、アプリケーションの"app.js"
ファイルが挙げられます。
".merge"
ファイルを処理する際、x-generate
により次の処理が行われます。
- ターゲットファイル(たとえば
"app.js"
)を退避させます(たとえば"app.js.$old"
などに名前を変更する)。 - 新しいバージョンのファイルを元の場所(この場合
"app.js"
)に生成します。 - データストアを使用してベースのバージョン(たとえば
"app.js.$base"
)を再生成します。つまり、このバージョンが最終的な生成を行います。 - これらのファイルに対して3方向のマージを行い、ターゲットファイルを更新します。
- マージに不整合があれば報告されます。
"app.js"
同様、".merge"
ファイルが".tpl"
であることは珍しくありません。たとえば"app.js"
の場合、ソースファイルは"app.js.tpl.merge"
です。
このモードを有効化するにはx-generate
にデータストア(JSONファイル)をポイントするstore
属性を付与することが必要です。
Sacredファイル
コード生成時、ファイルは2つの基本的なカテゴリに分かれます。すなわち、マシン管理とユーザー管理です。たとえ最終的にはユーザーが管理するファイルであっても、初期生成時には雛形となるファイルを提供することが望ましいといえます。
これは“sacred”ファイルといい、ソースファイルの拡張子".default"
で識別されます。つまり、ソースファイルは単なるデフォルトファイルであり、既存のファイルを置き換えるものではありません。
たとえば、雛形として"readme.txt"
ファイルを生成するが、ユーザーが加える変更を後続の再生成時に維持したい場合が挙げられます。この場合、ソースファイル名はreadme.txt.default
となります。
sacredファイルがテンプレートである場合もあります。これは、両方の拡張子をつけることで実現します。たとえば"readme.txt.tpl.default"
とします。この"readme.txt"
ファイルは、もともとはテンプレートを使用して生成されたsacredファイルです。
パラメーター
テンプレート生成にはデータまたはパラメーターが必要です。最も簡単なパラメーターの形式は、param
属性を使用したものです。
<x-generate ...>
<param name="bar" value="42" />
</x-generate>
パラメーターも次のようにファイルからロードできます。
<x-generate ...>
<load file="data.properties"/>
</x-generate>
次のファイルタイプは自動的に理解されます。
".cfg"
または".properties"
= 標準的はJavaプロパティファイル。".json"
= JSONデータファイル。
ファイルの拡張子がこれらのいずれでもないがプロパティファイルまたはJSONである場合、次に示すようにtype
属性をjson
またはproperties
と指定できます。
<x-generate ...>
<load file="data.props" type="properties" />
<load file="data" type="json" />
</x-generate>
注意:パラメーターは指定した順番に適用されます。名前が重複しているものがあった場合、置換されます。
x-generate file tofile
x-generate
の最もシンプルな形は、file
属性を使用して単一のテンプレートファイルを指定した出力ファイルに変換することです。
<x-generate file="foo.js.tpl" tofile="build/foo.js">
<param name="bar" value="42" />
</x-generate>
ソースファイル名により、処理方法(および使用するテンプレートエンジンと、sacredかどうか)が決まりますが、それだけです。
x-generate file todir
多くの場合、次のようにターゲットファイル名はそのままにしてフォルダのみを指定します。
<x-generate file="foo.js.tpl" todir="build">
<param name="bar" value="42" />
</x-generate>
これにより"foo.js"
が"build"
フォルダに(XTemplateを使用して)作成されます。
冗長性を回避するだけでなく、この形式ではソースファイル名をテンプレートとすることもできます。次に例を示します。
<x-generate file="{name}.js.tpl" todir="build">
<param name="name" value="foobar" />
<param name="bar" value="42" />
</x-generate>
ソースファイルファイルが指定した名前("{name}.js.tpl"
)で存在しますが、この名前はXTemplateエンジンとターゲットファイル名を決定するために指定されたパラメーターを使用して変換されます。
上記のケースでは、"foobar.js"
がbuild
ディレクトリに作成されます。
x-generate dir todir
x-generate
の最後の形式はソースフォルダに対して使用し、ターゲットフォルダにコンテンツを生成します。次に例を示します。
<x-generate dir="templates/foo" todir="build/foo">
<param name="bar" value="42" />
<load file="data.json"/>
</x-generate>
この形式では、ジェネレーターにより"templates/foo"
にあるファイルとサブフォルダが再帰的に読み込まれ、適切なテンプレートエンジンが適用されます。また、sacredファイルも保存します。ファイルとフォルダの名前はすべて、XTemplateテンプレートとして処理されます。
x-compress-js
次のオプション(属性)にしたがってJavaScriptソースを圧縮します。
srcfile
:圧縮するソースファイルです。outfile
:生成する出力ファイルです(デフォルト値はsrcfile)。charset
:入出力ファイルの文字エンコーディングです。header
:ファイル先頭のコメントブロックに記述するオプションのテキストです。linebreak
:改行位置を示す列番号です(デフォルト値は改行なしを示す-1)。obfuscate
:ローカルの記号を難読化しない場合はfalseを指定します(デフォルト値はtrue)。disableoptimizations
:組み込みの最適化処理をすべて無効化する場合はtrueを指定します。preservesemi
:セミコロンをすべて維持する場合はtrueを指定します。verbose
:追加の診断メッセージを有効化する場合はtrueを指定します。
x-compress-css
次のオプション(属性)にしたがってCSSソースを圧縮します。
srcfile
:圧縮するソースファイルです。outfile
:生成する出力ファイルです(デフォルト値はsrcfile)。charset
:入出力ファイルの文字エンコーディングです。header
:ファイル先頭のコメントブロックに記述するオプションのテキストです。linebreak
:改行位置を示す列番号です。verbose
:追加の診断メッセージを有効化する場合はtrueを指定します。
x-strip-js
JSファイルからコメント(行またはブロック)を削除するタスクです。サポートされるオプションは次のとおりです。
srcfile
:削除対象のソースファイルです。outfile
:生成する出力ファイルです(デフォルト値はsrcfile)。header
:ファイル先頭のコメントブロックに記述するオプションのテキストです。blockcomments
:ブロックコメント("/* … */“)を削除する場合はtrue(デフォルト)に設定します。/”).linecomments
:コメント行(“//”)を削除する場合はtrue(デフォルト値)を指定します。keepfirstcomment
:JSファイルの最初のコメントを維持する場合はtrue(デフォルト値)を指定します。通常、これは著作権で保護されています。whitespace
:空白も除去する場合はtrueを指定します。
x-get-env
環境変数値を指定したプロパティに保存します。環境変数名はまず大文字小文字を区別してマッチングされます。一致するものがない場合、大文字小文字の区別をせずにマッチングし、一致するものがあれば選択します。
<x-get-env name="PATH" property="env.path"/>
この処理は、環境変数読み取り時には“properties”タスクに優先して行われます。これは、環境変数(たとえば“Path”など)が、少なくともWindowsにおいては大文字と小文字を区別しないのに対し、Antプロパティは大文字小文字を区別するため、“properties”タスクでは変数の大文字小文字を区別するからです。
x-escape
このタスクでは文字列をエスケープし、その文字列を指定したプロパティに保存します。
<x-escape string="${some.text}" property="some.text.js" type="json"/>
<x-escape string="${some.text}" property="some.text.xml" type="xml"/>