irpack

irpack converts your IronRuby scripts to a standalone .exe file. Generated executable does not require IronRuby, but only .NET Framework or mono.

Requirements

IronRuby 1.1.3 or later.

Installation

$ igem install irpack

You need to use igem (gem command for IronRuby) instead of gem.

Usage

Command

$ irpack [options] ENTRYFILE [EMBEDFILES...]
  -b BASEDIR               Specify base directory. [base of ENTRYFILE]
  -o OUTPUTFILE            Specify output file name.
      --window             Generate window app.
      --console            Generate console app.[default]
      --compress           Compress package.
      --complete           Embed all standard libraries.
      --no-embed           Do not embed IronRuby assemblies.
Runtime options:
  -Idirectory              specify $LOAD_PATH directory (may be used more than once)
  -rlibrary                require the library, before executing your script
  -d                       set debugging flags (set $DEBUG to true)
  -D                       emit debugging information (PDBs) for Visual Studio debugger
  -v                       print version number, then turn on verbose mode
  -w                       turn warnings on for your script
  -W[level]                set warning level; 0=silence, 1=medium (default), 2=verbose
      --trace              enable support for set_trace_func
      --profile            enable support for 'pi = IronRuby::Clr.profile { block_to_profile }'
      --exception-detail   enable ExceptionDetail mode
      --no-adaptive-compilation
                           disable adaptive compilation - all code will be compiled
      --compilation-threshold THRESHOLD
                           the number of iterations before the interpreter starts compiling
      --pass-exceptions    do not catch exceptions that are unhandled by script code
      --private-binding    enable binding to private members
      --show-clr-exceptions
                           display CLS Exception information

Specify rb file on ENTRYFILE to generate exe. Executables includes ENTRYFILE and IronRuby dlls in their resource.

When runtime, script can open EMBEDFILES with relative path from BASEDIR.

for example:

$ irpack -o hoge/fuga.exe -b foo bar/entry.rb foo/hello.rb

hoge/fuga.exe runs embedded bar/entry.rb. To load foo/hello.rb, require ‘hello’ (relative path from BASEDIR ‘foo’). A real file is used if hello.rb exists in both embedded and real filesystem in same directory as executable.

To specify exe icon, embed ico file.

To generate application which has no console window use ‘–window’ option.

‘–no-embed’ option exclude IronRuby dlls from embedded files. A generated executable requires IronRuby dlls.

If scripts use any standard libraries, embed them too. ‘–complete’ embeds all of standard libraries into exe.

Executable file is compacted by ‘–compress’ option that compresses embedded files. To load compressed file costs extra time.

Runtime options are passed to script engine when generated executable started as well as ir.exe.

Rake task

In Rakefile:

require 'irpack/rake/generateexetask'

exe_spec = IRPack::Specification.new do |s|
  s.output_file      = 'example.exe'
  s.entry_file       = 'bin/main.rb'
  s.files            = Rake::Filelist['lib/**/*.rb']
  s.target           = :exe
  s.embed_stdlibs    = true
  s.embed_assemblies = true
  s.compress         = true
end

IRPack::Rake::GenerateExeTask.new(exe_spec) do |t|
end

Invoke ‘exe’ task to generate ‘example.exe’.

rake exe

If rake command is not exists, use ir.exe;

ir -rrake -e "Rake.application.run" exe

Limitations

Embedded native dlls and mixed (C++/CLI) assemblies are not loadable.

irpack

irpackはIronRubyのスクリプトを単体で動く.exeファイルに変換するアプリケーションで す。生成した実行ファイルは.NET FrameworkやmonoさえあればIronRubyをインストールし ていない環境でも動かすことができます。

動作環境

IronRuby 1.1.3以降。

インストール

$ igem install irpack

IronRubyでしか動かないのでigem (IronRubyのgemコマンド)を使ってインストールしてく ださい。

使い方

コマンド

$ irpack [options] ENTRYFILE [EMBEDFILES...]
  -b BASEDIR               埋め込み基準のディレクトリを指定します。[ENTRYFILEのあるディレクトリ]
  -o OUTPUTFILE            出力ファイル名を指定します。[ENTRYFILEの拡張子を.exeにしたもの]
      --window             ウィンドウアプリを生成します。
      --console            コンソールアプリを生成します。[default]
      --compress           パッケージの圧縮をします。
      --complete           全ての標準ライブラリを埋め込みます。
      --no-embed           IronRubyの埋め込みを行いません。
実行時オプション:
  -Idirectory              $LOAD_PATHディレクトリを指定します。(複数回指定できます。)
  -rlibrary                スクリプト実行前にlibraryを読み込みます。
  -d                       デバッグフラグを設定します。($DEBUGをtrueに設定します。)
  -D                       Visual Studioデバッガ用にデバッグ情報(PDB)を生成します。
  -v                       バージョン番号を出力し、冗長モードを有効にします。
  -w                       スクリプトの警告を有効します。
  -W[level]                警告レベルを設定します: 0=無し, 1=普通(デフォルト), 2=冗長
      --trace              set_trace_funcサポートを有効にします。
      --profile            CLRプロファイラを有効にします。次のように使います
                           'pi = IronRuby::Clr.profile { block_to_profile }'
      --exception-detail   例外詳細モードを有効にします。
      --no-adaptive-compilation
                           適応型コンパイルを無効にします。全てのコードがコンパイルされます。
      --compilation-threshold THRESHOLD
                           インタプリタがコンパイル開始するまでの繰り返し回数を指定します。
      --pass-exceptions    スクリプトで処理されなかった例外をcatchしないようにします。
      --private-binding    privateメンバへのバインディングを有効にします。
      --show-clr-exceptions
                           CLS例外情報を表示します。

ENTRYFILEに起動するrbファイルを指定するとexeファイルが生成されます。exeファイル にはENTRYFILEとIronRubyのdllが埋め込まれるので.NET Frameworkやmonoが入っている環 境でIronRubyのインストール無しに実行することができます。

ENTRYFILEに続けてファイルを指定することによって他のファイルもexeに埋め込むことが できます。

埋め込まれたファイルはスクリプト中からは「実行ファイルのディレクトリ/基準ディレク トリからの相対パス」に存在するように見えます。 たとえば、

$ irpack -o hoge/fuga.exe -b foo bar/entry.rb foo/hello.rb

としたときにfuga.exeの実行中(bar/entry.rb)からはfoo/hello.rbはhoge/hello.rb (fuga.exeのあるディレクトリhoge)にあるように見えます。 もしhoge/hello.rbが本当にファイルとして存在した場合はそちらが優先して開かれます。

EMBEDFILESにアイコン(.ico)ファイルを指定するとexeのアイコンとして使用します。

‘–console’や‘–window’オプションでコンソールアプリを生成するかウィンドウアプリを 生成するか指定できます。省略時はコンソールアプリになります。ウィンドウアプリの場 合はコンソールウィンドウが開かなくなりますが、標準入出力は使用できません。また例 外が捕捉されずに落ちた場合のメッセージは標準エラー出力に出るようになっていますが、 ウィンドウアプリの場合はそれも表示されません。

‘–no-embed’オプションを指定するとIronRuby.dllなどをexeに埋め込みません。配布する 場合は実行環境にIronRubyがインストールするかIronRuby.dllなどの必要なdllを同じディ レクトリに置いて実行してください。

標準ライブラリを使用する場合は、使用するライブラリも埋め込まなければいけません。 ‘–complete’オプションを指定すると標準ライブラリを全て埋め込みます。実行ファイル サイズはその分大きくなります。

‘–compress’オプションは埋め込んだファイルを圧縮します。実行ファイルのサイズが小さ くなりますが、読み込みに時間がかかるようになります。

実行時オプションは生成した実行ファイルの起動時にスクリプトエンジンに渡されます。 ir.exeに指定するのと同じものです。

Rakeタスク

Rakefileにて:

require 'irpack/rake/generateexetask'

exe_spec = IRPack::Specification.new do |s|
  s.output_file      = 'example.exe'
  s.entry_file       = 'bin/main.rb'
  s.files            = Rake::Filelist['lib/**/*.rb']
  s.target           = :exe
  s.embed_stdlibs    = true
  s.embed_assemblies = true
  s.compress         = true
end

IRPack::Rake::GenerateExeTask.new(exe_spec) do |t|
end

‘exe’タスクを起動すると‘example.exe’を生成することができます。

rake exe

rakeコマンドが無い場合はir.exeから起動できます。

ir -rrake -e "Rake.application.run" exe

制限

C++/CLIの混合アセンブリやネイティブdllは埋め込めません。

生成したexeは生成に使用したIronRubyと同じバージョンの.NET Frameworkかそれに対応 するmonoが必要です。 .NET Framework 4のir.exeを使って生成したexeを実行するには.NET Framework4か mono 2.8以降が必要ということです。

License

zlib/libpng License.

Copyright (c) 2010-2011 Ryuichi Sakamoto.

This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

    1. The origin of this software must not be misrepresented; you must not
    claim that you wrote the original software. If you use this software
    in a product, an acknowledgment in the product documentation would be
    appreciated but is not required.

    2. Altered source versions must be plainly marked as such, and must not be
    misrepresented as being the original software.

    3. This notice may not be removed or altered from any source
    distribution.