Skip to content

Latest commit

 

History

History
213 lines (144 loc) · 9.67 KB

README.md

File metadata and controls

213 lines (144 loc) · 9.67 KB
Raw

Notes on this Fork

  • Built rubyc files for mac/linux are now found here. I don't have a windows machine, so I have not had a chance build a windows ruby. I'd love a contribution.
  • Note that if you want to support M1 and Intel macs, you need to build a separate packed binary for each one on the correct type of machine. I haven't found a way around that!
  • History: This fork started as just some tweaks to the motor-admin fork to get it working on Ruby 3.1.0 for me. This works with Ruby 3.1.3 now and MacOs Ventura, thank-you @taraszka!
  • As a tip, the embedded filesystem runs a bit slow. This mainly matters when your app is doing many heavy requires, like the AWS ruby gem. One workaround is to autoload your requires. Autoload works well for cases when there's a constant that can be used to trigger the require for a particular item. For example, accessing JSON triggers the require of 'json' in the example below. For items that aren't used in every codepath, this strategy can greatly minimize your total requires, assuming you don't need every require
autoload :JSON, 'json'
# 'json' isn't loaded yet

JSON.parse(doc)
# now 'json' is, it was loaded on the fly

Autoload was being considered for deprecation, but that's no longer the case, so fear not.

Ruby Packer

Packing your Ruby application into a single executable.

Windows macOS Linux

Features

It takes less than 5 minutes to compile any project with Ruby Packer.

You won't need to modify a single line of code in your application, no matter how you developed it as long as it works in plain Ruby!

  • Works on win Windows, macOS macOS and linux Linux
  • Windows is supported via the native Windows API; there are no MSYS2/MinGW/Cygwin dependencies
  • Creates a binary distribution of your Ruby and/or Rails application
  • Supports natively any form of require and load, including dynamic ones (e.g. load(my_path + '/x.rb'))
  • Ruby Packer is written in Ruby and is packed and distributed using Ruby Packer itself
  • Native C extensions are fully supported
  • Open Source, MIT Licensed

Known Limitations

  • Some gems that use C extensions that use libc IO to load files from your Rails application will not work with rubyc. Notably, bootsnap will not work with rubyc
  • On macOS and Linux, DTrace is currently disabled, see pmq20#114

Download

Stable Releases

Built rubyc files for the latest releases can be found here:

Currently windows may work, but it is untested, and you'll need to build rubyc on your own.

Install

win Install on Windows

First install the prerequisites:

Then download rubyc.exe from either Unstable Pre-release or Stable Releases. Optionally, put it under C:\Windows or any other PATH directories. Open Visual Studio's "x64 Native Tools Command Prompt" and execute rubyc --help therein.

macOS Install on macOS

First install the prerequisites:

  • SquashFS Tools: brew install squashfs
  • Xcode
    • You also need to install the Command Line Tools via Xcode. You can find this under the menu Xcode -> Preferences -> Downloads
    • This step will install gcc and the related toolchain containing make
  • Ruby

Then download rubyc from either Unstable Pre-release or Stable Releases. Run chmod +x to give it execution permissions and execute ./rubyc --help.

linux Install on Linux

First install the prerequisites:

  • SquashFS Tools
    • sudo yum install squashfs-tools
    • sudo apt install squashfs-tools
  • gcc or clang
  • GNU Make
  • Ruby

Then download rubyc from either Unstable Pre-release or Stable Releases. Run chmod +x to give it execution permissions and execute ./rubyc --help.

Usage

rubyc [OPTION]... [ENTRANCE_FILE]

ENTRANCE_FILE refers to the path of an executable ruby script from your project, e.g. "bin/rails".
If ENTRANCE_FILE was not provided, a single raw Ruby interpreter executable would be produced.

-r, --root=DIR                   The path to the root of your application
-o, --output=FILE                The path of the output file
-d, --tmpdir=DIR                 The directory for temporary files
    --keep-tmpdir                Keeps all temporary files that were generated last time
    --openssl-dir                The path to the dir containing cert.pem
    --make-args=ARGS             Extra arguments to be passed to make
    --nmake-args=ARGS            Extra arguments to be passed to nmake
-i, --ignore-file=STRING         Ignore file(s) from build
    --debug                      Enable debug mode
    --quiet                      Enable quiet mode
-v, --version                    Prints the version of rubyc and exit
-V, --ruby-version               Prints the version of the Ruby runtime and exit
    --ruby-api-version           Prints the version of the Ruby API and exit
-h, --help                       Prints this help and exit

The --openssl-dir Option

rubyc compiles its own version of openssl without any certifications. To be able to use ssl with rubyc it should know where to find the certifications.

By default this path is set to /usr/local/etc/openssl/ but can be overridden using the --openssl-dir argument.

Keep in mind that users running your compiled package should have their certifications present in this directory as well.

If you're building for macOS, you should set --openssl-dir to /private/etc/ssl.

The --ignore-file Option

If you don't want certain files included in the build you can ignore them from the command line using -i.

rubyc -i ignore.file -i ignore-2.file -i "ignore*"

Alternatively you can create a .rubycignore file in the root of your project to specify which files should be ignored.

Examples

Producing a Portable Ruby Interpreter Executable

I.e. packing the raw Ruby interpreter without packing any projects:

rubyc
./a.out (or a.exe on Windows)

Packing a CLI utility

Taking Ruby Packer itself as an example of the CLI utility to pack:

git clone --depth 1 https://github.com/pmq20/ruby-packer
cd ruby-packer
rubyc bin/rubyc
./a.out (or a.exe on Windows)

Packing a Rails Application

rails new yours
cd yours
rubyc bin/rails
./a.out server (or a.exe server on Windows)

Building rubyc from Source

To build rubyc you must have a C compiler and the necessary toolchain to build ruby and the libraries stuffed inside rubyc which include at least:

  • gdbm
  • libffi
  • ncurses
  • openssl
  • readline
  • yaml
  • zlib

If you are unsure if your toolchain is complete then trying to build rubyc will let you know you are missing something. Unfortunately it may tell you with some unfamiliar message. Please file an issue here if this occurs.

Once your toolchain is set up run bundle. To compile your own rubyc run:

bundle exec rake rubyc

Or (if you want to compile with debug symbols):

ENCLOSE_IO_RUBYC_ADDTIONAL_ARGS=--debug bundle exec rake rubyc

This will produce a single rubyc executable, which can be put inside any of your PATH locations, so that it can be directly called from the command prompt. For example:

mv rubyc /usr/local/bin

Remember that rubyc includes all the files from the current directory in the built executable. You must delete the prior rubyc or your squashfs will continually grow larger and the embedded squashfs compile time will be very, very long.

Authors

Minqi Pan et al.

License

MIT

See Also