レシピファイルは、実行ファイルの生成に必要な各種情報を記述するテキストファイルです。 各種情報は、YAML（YAML Ain't Markup Language）フォーマットで記述し、文字コードにはUTF-8を使用します。
もっとも単純なレシピファイルの例は、下記の通りです。
general:
startup: hello.rb
file:
hello.rb:
YAMLフォーマットについて、簡単に解説します。
YAMLでは、いくつかの記号とインデントを用いて、データ構造を表現します。 データ構造には大きく分けて、配列とハッシュという2種類があります。
下記に例を記述すると共に、「#=>」という記号に続き、Ruby上におけるデータを併記します。
配列は、下記の形式で記述します。
- 値
下記のように記述することで、配列を表現します。
- Array
- String
- 123
#=> ["Array", "String", 123]
Ruby上ではArrayオブジェクトとして扱われます。
ハッシュは、下記の形式で記述します。
キー: 値
下記のように記述することで、ハッシュを表現します。
Type: Hash
String: ABC
Number: 123
#=> {"Type" => "Hash", "String" => "ABC", "Number" => 123}
Ruby上ではHashオブジェクトとして扱われます。 そのため、キーの順序は保存されません。
配列とハッシュは、それぞれ組み合わせることができます。 インデントすることによって、親子関係を示します。 インデントにはスペース文字、タブ文字が使用できますが、2個のスペース文字を用いることを推奨します。
配列同士の組み合わせ例は、下記の通りです。
-
- 1x1
- 1x2
-
- 2x1
- 2x2
#=> [["1x1", "1x2"], ["2x1", "2x2"]]
ハッシュ同士の組み合わせ例は、下記の通りです。
Key1:
Type: String
Value: ABC
Key2:
Type: Number
Value: 123
#=> {"Key1" => {"Type" => "String", "Value" => "ABC"},
"Key2" => {"Type" => "Number", "Value" => 123}}
配列とハッシュの組み合わせ例は、下記の通りです。
String:
- A
- B
- C
Number:
- 1
- 2
- 3
#=> {"String" => ["A", "B", "C"], "Number" => [1, 2, 3]}
レシピファイルは下記のブロック（ハッシュ構造）から構成されています。 各ブロックの記述順序は任意ですが、下記の順序で記述することを推奨します。
なお、日本語を含む場合はUTF-8でエンコードしてください。
生成する実行ファイルについての基本的な情報を指定します。 このブロックは必須です。
general:
startup: foo.rb
output: bar.exe
core: cui
kcode: sjis
startupキーは、実行ファイル起動時に、最初に実行するRubyスクリプトのファイル名を指定します。 このキーは必須です。
outputキーは、生成する実行ファイルの出力ファイル名を指定します。 省略された場合、レシピファイルのファイル名が使用されます。 レシピファイルの拡張子が「exy」であれば拡張子を「exe」に置換したファイル名、そうでなければ「.exe」を付加したファイル名を使用します。 コマンドオプションで出力ファイル名が指定された場合、コマンドオプションによる指定が優先されます。
coreキーは、実行ファイルの生成に使用するExerbコアを指定します。 定義名、またはファイル名で指定します。 コマンドオプションでコアが指定された場合、コマンドオプションによる指定が優先されます。
kcodeキーは、Rubyスクリプトの文字コードを指定します。 rubyコマンドの-Kオプションに相当します。 コマンドオプションで文字コードが指定された場合、コマンドオプションによる指定が優先されます。 文字コードは、下記のいずれかを指定してください。
| 指定値 | 意味 |
|---|---|
| none | 指定なし（デフォルト） |
| euc | EUC |
| sjis | Shift-JIS |
| utf8 | UTF-8 |
Rubyスクリプト、拡張ライブラリ等の検索パスを指定します。 絶対パス、またはレシピファイルが存在するディレクトリを基準とした相対パスで記述します。
path:
- ..\lib\so
- c:\ruby\lib
- c:\ruby
生成する実行ファイルのリソース情報を指定します。
このブロックは、実行ファイルのアイコンリソースを指定するiconブロックと、 バージョン情報リソースを指定するversionブロックで構成されています。
アイコンリソースを指定します。 このブロックが省略された場合、コアに含まれているデフォルトのアイコンが使用されます。 複数のサイズ、色数のアイコンを指定することができますが、メインアイコン以外のアイコンリソースを指定することはできません。
resource:
icon:
-
width : 16
height: 16
color : 4
file : file.ico
widthキーは、アイコンの横方向のピクセル数（幅）を指定します。
heightキーは、アイコンの縦方向のピクセル数（高さ）を指定します。
colorキーは、アイコンの色深度のビット数を指定します。例えば、16色であれば4ビットです。
fileキーは、上記の3つのキーで指定したアイコンが含まれているファイルを指定します。 複数のサイズ、色数が含まれているアイコンファイルを指定することができますが、アイコンリソースとして使用されるのは、上記3つのキーで指定したアイコンのみです。
バージョン情報リソースを指定します。 このブロックが省略された場合、コアに含まれているデフォルトのバージョン情報が使用されます。
resource:
version:
file_version_number : 1.2.3.4
product_version_number: 5.6.7.8
comments : コメント
company_name : 会社名
legal_copyright : 著作権情報
legal_trademarks : 商標情報
file_version : ファイルバージョン（文字列）
product_version : 製品バージョン（文字列）
product_name : 製品名
file_description : ファイルの説明
internal_name : 内部名
original_filename : 正式ファイル名
private_build : プライベートビルド情報
special_build : スペシャルビルド情報
file_version_numberキー、product_version_numberキーには、それぞれファイルバージョン、製品バージョンをドットで区切られた4つの数値で指定します。 それぞれの数値には、0〜65535の範囲を使用することができます。
その他のキーは、文字列でそれぞれの内容を指定します。 日本語文字列を使用する場合は、レシピファイルをUTF-8でエンコードしてください。
生成する実行ファイルに格納するファイルを指定します。 このブロックは必須です。
file:
foo.so:
file: foo/foo.so
type: extension-library
キー名には、ファイル名を指定します。 このファイル名は内部ファイル名と呼ばれ、requireメソッドによるファイルの読み込みで使用されます。 内部ファイル名は、パスの区切り文字も含めて単一の文字列として比較されるため、「require "../foo/bar.so"」などは正しく解釈されないので注意してください。 前述のrequireメソッド呼び出しでは「../foo/bar.so」という内部ファイル名が検索されます。
fileキーには、実際のファイル名を指定します。 内部ファイル名と同一の場合、または検索パスより検索可能な場合は、省略することができます。
typeキーには、ファイルの種別を指定します。 省略された場合は、ファイルの拡張子に基づいて種別が決定されます。
| 拡張子 | 種別 | 説明 |
|---|---|---|
| .rb | script （Rubyスクリプト） | Rubyスクリプトが記述されたテキストファイル。requireにて読み込むことができます。 |
| .so | extension-library （拡張ライブラリ） | C言語などで作成された拡張ライブラリ（ダイナミックリンクライブラリ）。requireにて読み込むことができます。 |
| .dll | dynamic-library （ダイナミックリンクライブラリ） | 拡張ライブラリが使用するダイナミックリンクライブラリ。拡張ライブラリによって要求された場合に、自動的に読み込まれます。明示的に読み込むことはできません。 |
| .res | resource-library （リソースライブラリ） | リソースのみが格納されたダイナミックリンクライブラリ。Exerb実行時モジュールを使用してリソースデータを読み込むことができます。 |
| .dat | data （データ） | バイナリ、画像、データベースなどのデータファイル。Exerb実行時モジュールを使用して読み込むことができます。書き込みはできません。 |
実行時モジュールについては『クラスリファレンス』を参照してください。