-
Homepage: ocra.rubyforge.org
-
RubyForge project page: rubyforge.org/projects/ocra
-
GitHub: github.com/larsch/ocra
-
Issue tracker: github.com/larsch/ocra/issues
-
Google Group: groups.google.com/group/ruby-ocra
OCRA (One-Click Ruby Application) builds Windows executables from Ruby source code. The executable is a self-extracting, self-running executable that contains the Ruby interpreter, your source code and any additionally needed ruby libraries or DLL.
-
LZMA Compression (optional, default on)
-
Windows support only
-
Ruby 1.9 support
-
Both windowed/console mode supported
If you experience problems with OCRA or have found a bug, please use the issue tracker on GitHub (github.com/larsch/ocra/issues). You can also join the Google Group discussion forum to ask questions and get help (groups.google.com/group/ruby-ocra).
ocra script.rb
Will package “script.rb”, the Ruby interpreter and all dependencies (gems and DLLs) into an executable named “script.exe”.
ocra [options] script.rb [<other files> ...] [-- <script arguments> ...]
ocra --help --dll dllname Include additional DLLs from the Ruby bindir. --no-lzma Disable LZMA compression of the executable. --quiet Suppress output. --help Display this information. --windows Force Windows application (rubyw.exe) --console Force console application (ruby.exe) --no-autoload Don't load/include script.rb's autoloads --icon <ico> Replace icon with a custom one --version Display version number --no-gem-filter Don't filter readme's, doc, C-source, etc. from gems
-
OCRA 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 OCRA 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.
-
The ‘current working directory’ is not changed by OCRA when running your application. You must change to the installation or temporary directory yourself. See also below.
-
When the application is running, the OCRA_EXECUTABLE environment variable points to the .exe (with full path).
-
The temporary location of the script can be obtained by inspected the $0 variable.
-
OCRA 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.
-
Avoid modifying load paths at run time. Specify load paths using -I or RUBYLIB if you must, but don’t expect OCRA to preserve them for runtime. OCRA may pack sources into other directories than you expect.
-
If you use .rbw files or the
--windowsoption, then check that your application works with rubyw.exe before trying with OCRA. -
Avoid absolute paths in your code and when invoking OCRA.
-
Windows
-
Working Ruby installation, tested with:
-
One-Click Installer (187_27_rc2)
-
RubyInstaller (1.8.7p299, 1.9.1p249, 1.9.2p0)
-
-
MinGW Installation (when working with the source code only)
Install by running:
gem install ocra
Get ocrasa.rb from rubyforge.org/frs/?group_id=8185. Requires nothing but a working Ruby installation on Windows.
OCRA first runs the target script in order to detect any files that are loaded and used at runtime (Using Kernel#require and Kernel#load).
OCRA 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 OCRA script generates this executable and the instructions to be run when it is launched.
When executed, the OCRA stub extracts the Ruby interpreter and your scripts into a temporary directory. The directory will contains the same directory layout as your Ruby installlation. The source files for your application will be put in the ‘src’ subdirectory.
Any code that is loaded through Kernel#require when your script is executed will be included in the OCRA executable. Conditionally loaded code will not be loaded and included in the executable unless the code is actually run when OCRA invokes your script. Otherwise, OCRA won’t know about it and will not include the source files.
RubyGems are handled specially. Whenever a file from a Gem is detected, OCRA will attempt to include all the files from that specific Gem (all files listed in the manifest), expect some unlikely needed files such as readme’s and other documentation. This latter can be overruled using the “--no-gem-filter” which will make OCRA include every file that is listed in the Gem’s manifest.
Libraries found in non-standard path (for example, if you invoke OCRA 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 OCRA 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, OCRA 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 OCRA.
OCRA executables clear the RUBYLIB environment variable before your script is launched. This is done to ensure that your script does not use load paths from the end user’s Ruby installation.
OCRA executables set the RUBYOPT environment variable to the value it had when you invoked OCRA. For example, if you had “RUBYOPT=rubygems” on your build PC, OCRA ensures that it is also set on PC’s running the executables.
OCRA executables set OCRA_EXECUTABLE to the full path of the executable, for example
ENV["OCRA_EXECUTABLE"] # => C:\Program Files\MyApp\MyApp.exe
The OCRA executable does not change the working directory when it is launched.
You should not assume that the current working directory when invoking an executable built with .exe is the location of the source script. It can be the directory where the executable is placed (when invoked through the Windows Explorer), the users’ current working directory (when invoking from the Command Prompt), or even C:\WINDOWS\SYSTEM32 when the executable is invoked through a file association. You can optionally change the directory yourself:
Dir.chdir File.dirname($0)
If you wish to maintain the user’s working directory, but need to ‘require’ additional Ruby scripts from the source directory, you can add the following line to your script:
$LOAD_PATH.unshift File.dirname($0)
Adding paths to $LOAD_PATH or $: at runtime is not recommended. Adding relative load paths depends on the working directory being the same as where the script is located (See above). If you have additional library files in directories below the directory containing your source script you can use this idiom:
$LOAD_PATH.unshift File.join(File.dirname($0), 'path/to/script')
You can detect whether OCRA is currently building your script by looking for the ‘Ocra’ constant. If it is defined, OCRA is currenly building the executable from your script. For example, you can use this to avoid opening a GUI window when compiling executables:
app = MyApp.new if not defined?(Ocra) app.main_loop end
You can add additional files to the OCRA executable (for example images) by appending them to the command line. They should be placed in the source directory with your main script (or a subdirectory).
ocra mainscript.rb someimage.jpeg docs/document.txt
This will create the following layout in the temporary directory when your program is executed:
src/mainscript.rb src/someimage.jpeg src/docs/document.txt
Paths on the command line can include ** globs to include a hierachy of files, for example
ocra script.rb assets/**/*.png
To pass command line argument to your script (both while building and when run from the resulting executable), specify them after a “--” marker. For example:
ocra script.rb -- --some-options=value
This will pass “--some-options=value” to the script when build and when running the executable. Any extra argument specified by the user when invoking the executable will be appended after the compile-time arguments.
By default, OCRA builds console application from .rb-files and windowed applications (without console window) from .rbw-files.
Ruby on Windows provides two executables: ruby.exe is a console mode application and rubyw.exe is a windowed application which does not bring up a console window when launched using the Windows Explorer. By default, or if the “--console” option is used, OCRA will use the console runtime (rubyw.exe). OCRA will automatically select the windowed runtime when your script has the “.rbw” extension, or if you specify the “--windows” command line option.
If your application works in console mode but not in windowed mode, first check if your script works without OCRA using rubyw.exe. A script that prints to standard output (using puts, print etc.) will eventually cause an exception when run with rubyw.exe (when the IO buffers run full).
You can also try wrapping your script in an exception handler that logs any errors to a file:
begin # your script here rescue Exception => e File.open("except.log") do |f| f.puts e.inspect f.puts e.backtrace end end
Thanks for Igor Pavlov for the LZMA compressor and decompressor. The source code used was place into Public Domain by Igor Pavlov.
Erik Veenstra for rubyscript2exe which provided inspiration.
Dice for the default .exe icon (vit-ruby.ico, ruby.morphball.net/vit-ruby-ico_en.html)
(The MIT License)
Copyright © 2009-2010 Lars Christensen
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.