Traveling Ruby Documentation

Traveling Ruby solves the problem of distributing portable Ruby binaries by providing a 'holy build box'—a tightly controlled build environment.

Instead of using static linking (which is problematic for Ruby because it prevents the dynamic loading of Ruby extensions/shared libraries), Traveling Ruby uses a dynamic linking approach with specific safeguards:

1. Old glibc symbols: The binaries are dynamically linked against the C library but use older symbol versions to ensure compatibility with older Linux systems.
2. Bundled dependencies: It ships carefully-compiled versions of essential shared libraries (e.g., OpenSSL, ncurses, libedit) to prevent accidental linking to non-standard or version-mismatched libraries on the user's OS.

This approach ensures that your application remains stable even if the user's OS version changes or if they have different versions of system libraries installed.

Even if a target platform (like macOS) ships with Ruby, you should bundle a Ruby interpreter with your application for the following reasons:

• Version Consistency: Different OS versions ship different Ruby versions. Bundling ensures your app isn't broken by OS upgrades.
• Language Syntax Compatibility: Significant changes in Ruby (such as keyword argument changes in Ruby 2.7+) can break code if the user's system Ruby is a different version than what you developed for.
• Avoiding Installation Friction: Relying on system Ruby forces users to deal with complex installation methods (RVM, rbenv, apt-get, yum, etc.), PATH issues, and sudo permission conflicts with GEM_HOME.
• Predictable Environment: Bundling avoids the 'command not found' errors and environment variable resets (like those caused by sudo or rvmsudo) that occur when users try to install dependencies via RubyGems on a system-wide Ruby.

A wrapper script is required to launch your application. It must perform three tasks:

1. Determine its own location to resolve relative paths.
2. Set the BUNDLE_GEMFILE environment variable to point to the Gemfile inside the package's lib/vendor/ directory.
3. Execute the application using the bundled Ruby interpreter with bundler/setup required to activate the gem environment.

Note: You must unset BUNDLE_IGNORE_CONFIG in the script if you previously set it in your environment to ensure the local .bundle/config is respected.

#!/bin/bash
set -e

# Figure out where this script is located.
SELFDIR="`dirname "$0"`"
SELFDIR="`cd "$SELFDIR" && pwd`"

# Tell Bundler where the Gemfile and gems are.
export BUNDLE_GEMFILE="$SELFDIR/lib/vendor/Gemfile"
unset BUNDLE_IGNORE_CONFIG

# Run the actual app using the bundled Ruby interpreter, with Bundler activated.
exec "$SELFDIR/lib/ruby/bin/ruby" -rbundler/setup "$SELFDIR/lib/app/hello.rb"

To support Windows, you need to modify your Rakefile to handle .zip creation instead of .tar.gz and to download the correct Windows binaries.

Follow these steps to update your Rakefile:

1. Add a task to download Windows binaries: Add a file task that uses download_runtime("win32").

2. Add the package:win32 task: Define a task within the package namespace that depends on :bundle_install and the downloaded runtime.

3. Update create_package signature: Modify the create_package method to accept an os_type parameter (defaulting to :unix).

4. Update wrapper copying logic: Use a conditional to copy wrapper.bat and rename it to hello.bat when os_type is not :unix.

5. Update archive creation logic: Use a conditional to use the zip command instead of tar when targeting Windows.

6. Update the main package task: Add 'package:win32' to the dependencies of the package task.

# 1. Download task
file "packaging/traveling-ruby-#{TRAVELING_RUBY_VERSION}-win32.tar.gz" do
  download_runtime("win32")
end

# 2. Package task
namespace :package do
  desc "Package your app for Windows x86"
  task :win32 => [:bundle_install, "packaging/traveling-ruby-#{TRAVELING_RUBY_VERSION}-win32.tar.gz"] do
    create_package("win32", :windows)
  end
end

# 3. Updated method signature
def create_package(target, os_type = :unix)
  # ... logic ...
end

# 4. Conditional wrapper copying
if os_type == :unix
  sh "cp packaging/wrapper.sh #{package_dir}/hello"
else
  sh "cp packaging/wrapper.bat #{package_dir}/hello.bat"
end

# 5. Conditional archiving
if os_type == :unix
  sh "tar -czf #{package_dir}.tar.gz #{package_dir}"
else
  sh "zip -9r #{package_dir}.zip #{package_dir}"
end

# 6. Update main task
task :package => ['package:linux:x86', 'package:linux:x86_64', 'package:osx', 'package:win32']