Aibika

= Aibika: Ruby applications in a single executable on Windows

== Purpose

Aibika packages a Ruby application into a single executable for the Windows platform.

The resulting executable is self-extracting and self-running, containing:

• the Ruby interpreter;
• packaged Ruby source code; and
• any additionally needed Ruby libraries or DLLs.

NOTE: Aibika was created from the Metanorma-enhanced fork of the https://github.com/larsch/ocra[One-click Ruby Application "Ocra" packager]. The first Aibika version was launched as 1.3.12. The last version of Ocra was 1.3.11 from 2020.

NOTE: Aibika is considered a temporary solution to the full-fledged functionality of https://github.com/tamatebako/tebako[Tebako], which provides a user-space mounted-disk experience with minimal intervention.

== Supported platforms

Aibika only supports Windows.

== Supported Ruby versions

The Aibika packager supports the following versions of Ruby for packaging:

• 2.7.7
• 3.0.6
• 3.1.4
• 3.2.2

== Features

• LZMA Compression (optional, default on)
• Both windowed/console mode supported
• Includes gems based on usage, or from a Bundler Gemfile

== Installation

[source,sh]

gem install aibika

// Stand-alone version: Get abika.rb from // https://github.com/tamatebako/aibika/releases/ // Requires nothing but a working Ruby and MinGW installations on Windows

== Migration from Ocra

Aibika 1.3.12 is fully compatible with Ocra 1.13.11 In order to migrate your build scripts replace ocra invokations with aibika.

== Synopsis

=== Building an executable

[source,sh]

$ aibika script.rb

Will package script.rb, the Ruby interpreter and all dependencies (gems and DLLs) into an executable named script.exe.

=== Command line

[source,sh]

$ aibika [options] script.rb [<other files> ...] [-- <script arguments> ...]

=== Options

[source,sh]

$ aibika --help

Aibika options:

[source]

--help Display this information. --quiet Suppress output while building executable. --verbose Show extra output while building executable. --version Display version number and exit.

Packaging options:

[source]

--dll dllname Include additional DLLs from the Ruby bindir. --add-all-core Add all core ruby libraries to the executable. --gemfile <file> Add all gems and dependencies listed in a Bundler Gemfile. --no-enc Exclude encoding support files --allow-self Include self (aibika gem) if detected or specified This option is required only if aibika gem is deployed as a part of broader bundled solution

Gem content detection modes:

[source]

--gem-minimal[=gem1,..] Include only loaded scripts --gem-guess=[gem1,...] Include loaded scripts & best guess (DEFAULT) --gem-all[=gem1,..] Include all scripts & files --gem-full[=gem1,..] Include EVERYTHING --gem-spec[=gem1,..] Include files in gemspec (Does not work with Rubygems 1.7+)

--[no-]gem-scripts[=..] Other script files than those loaded --[no-]gem-files[=..] Other files (e.g. data files) --[no-]gem-extras[=..] Extra files (README, etc.)

Gem modes:

• minimal: loaded scripts
• guess: loaded scripts and other files
• all: loaded scripts, other scripts, other files (except extras)
• full: Everything found in the gem directory

File groups:

• scripts: .rb/.rbw files
• extras: C/C++ sources, object files, test, spec, README
• files: all other files

Auto-detection options:

---

--no-dep-run Don't run script.rb to check for dependencies. --no-autoload Don't load/include script.rb's autoloads. --no-autodll Disable detection of runtime DLL dependencies.

Output options:

---

--output <file> Name the exe to generate. Defaults to ./<scriptname>.exe. --no-lzma Disable LZMA compression of the executable. --innosetup <file> Use given Inno Setup script (.iss) to create an installer.

Executable options:

---

--windows Force Windows application (rubyw.exe) --console Force console application (ruby.exe) --chdir-first When exe starts, change working directory to app dir. --icon <ico> Replace icon with a custom one. --debug Executable will be verbose. --debug-extract Executable will unpack to local dir and not delete after.

=== Compilation

• Aibika will load your script (using Kernel#load) and build the executable when it exits.

• Your program should 'require' all necessary files when invoked without arguments, so Aibika can detect all dependencies.

• DLLs are detected automatically but only those located in your Ruby installation are included.

• .rb files will become console applications. .rbw files will become windowed application (without a console window popping up). Alternatively, use the --console or --windows options.

=== Running your application

• The 'current working directory' is not changed by Aibika when running your application. You must change to the installation or temporary directory yourself. See also below.
• When the application is running, the AIBIKA_EXECUTABLE environment variable points to the .exe (with full path).
• The temporary location of the script can be obtained by inspected the $0 variable.
• Aibika does not set up the include path. Use $:.unshift File.dirname($0) at the start of your script if you need to require additional source files from the same directory as your main script.

=== Pitfalls

• Avoid modifying load paths at run time. Specify load paths using -I or RUBYLIB if you must, but don't expect Aibika to preserve them for runtime. Aibika may pack sources into other directories than you expect.
• If you use .rbw files or the --windows option, then check that your application works with rubyw.exe before trying with Aibika.
• Avoid absolute paths in your code and when invoking Aibika.

== Requirements

• Windows
• Working Ruby installation
• MinGW Installation

== Aibika examples available at https://tebako.org[a tebako blog]

• https://www.tebako.org/blog/2023-08-24-introducing-aibika-and-ocra[Single-file packaging]
• https://www.tebako.org/blog/2023-08-24-introducing-aibika-and-ocra[Packaging with Gemfile]

== Technical details

Aibika first runs the target script in order to detect any files that are loaded and used at runtime (Using Kernel#require and Kernel#load).

Aibika embeds everything needed to run a Ruby script into a single executable file. The file contains the .exe stub which is compiled from C-code, and a custom opcode format containing instructions to create directories, save files, set environment variables and run programs. The Aibika script generates this executable and the instructions to be run when it is launched.

When executed, the Aibika stub extracts the Ruby interpreter and your scripts into a temporary directory. The directory will contains the same directory layout as your Ruby installation. The source files for your application will be put in the 'src' subdirectory.

=== Libraries

Any code that is loaded through Kernel#require when your script is executed will be included in the Aibika executable. Conditionally loaded code will not be loaded and included in the executable unless the code is actually run when Aibika invokes your script. Otherwise, Aibika won't know about it and will not include the source files.

RubyGems are handled specially. Whenever a file from a Gem is detected, Aibika will attempt to include all the required files from that specific Gem, expect some unlikely needed files such as readme's and other documentation. This behaviour can be controlled by using the --gem-* options. Behaviour can be changed for all gems or specific gems using --gem-*=gemname.

Libraries found in non-standard path (for example, if you invoke Aibika with ruby -I some/path) will be placed into the site dir (lib/ruby/site_ruby). Avoid changing $LOAD_PATH or $: from your script to include paths outside your source tree, since Aibika may place the files elsewhere when extracted into the temporary directory.

In case your script (or any of its dependencies) sets up autoloaded module using Kernel#autoload, Aibika will automatically try to load them to ensure that they are all included in the executable. Modules that doesn't exist will be ignored (a warning will be logged).

Dynamic link libraries (.dll files, for example WxWidgets, or other source files) will be detected and included by Aibika.

=== Including libraries non-automatically

If an application or framework is complicated enough that it tends to confuse Aibika's automatic dependency resolution, then you can use other means to specify what needs to be packaged with your app.

To disable automatic dependency resolution, use the --no-dep-run option; with it, Aibika will skip executing your program during the build process. This on the other hand requires using --gem-full option (see more below); otherwise Aibika will not include all the necessary files for the gems.

You will also probably need to use the --add-all-core option to include the Ruby core libraries.

If your app uses gems, then you can specify them in a Bundler Gemfile, then use the --gemfile option to supply it to Aibika. Aibika will automatically include all gems specified, and all their dependencies.

NOTE: This assumes that the gems are installed in your system, not locally packaged inside the app directory by "bundle package".

These options are particularly useful for packaging Rails applications. For example, to package a Rails 3 app in the directory "someapp" and create an exe named "someapp.exe", without actually running the app during the build, you could use the following command:

[source,sh]

$ aibika someapp/script/rails someapp --output someapp.exe --add-all-core
--gemfile someapp/Gemfile --no-dep-run --gem-full --chdir-first -- server

Note the space