Skip to content
This repository

A rake task generator to help with building/packaging/deploying Ruby applications for release (builds for win32/OS X and source, building on all platforms).

branch: master

Merge pull request #53 from 8bitsofme/local-deploy-fix

Remove force from copy in local distribute
latest commit ea30ef3cea
Bil Bas authored
README.md

Releasy

Releasy automates the release of Ruby applications, such as games or GUI applications, for non-Ruby users. By configuring a {Releasy::Project} in your application's Rakefile, Releasy can generate Rake tasks for use when there is a need to build, package (archive) and/or deploy a new version of the application.

Features and Limitations

Features

  • Package up Ruby applications (Games, GUI applications, etc.) for non-ruby users.
  • Build OS X application bundle (.app) on any platform.
  • Build Windows executable (.exe) on any platform.
  • Build Windows installer (Windows only).
  • Build, package (compress) and deploy your executables for all platforms from a single rake command ('rake deploy').

Limitations

  • Building Windows executable on non-Windows systems will not work with compiled gems that aren't published as pre-compiled for Windows (i386-mingw or x86-mingw).
  • Building OS X apps on non-OS X systems will not currently work with compiled gems at all (other than Gosu, Chipmunk & TexPlay).
  • One or more external applications need to be installed, separate to the Releasy gem (see below for details).
  • :windows_wrapped executable with Ruby 1.8.7, 1.9.2 and 1.9.3 only.
  • :osx_app executable with Ruby 1.9.2 only.

Installation

    $ gem install releasy

Example

Project's Rakefile

  require 'rubygems'
  require 'bundler/setup' # Releasy requires require that your application uses bundler.
  require 'releasy'

  #<<<
  Releasy::Project.new do
    name "My Application"
    version "1.3.2"
    verbose # Can be removed if you don't want to see all build messages.

    executable "bin/my_application.rb"
    files "lib/**/*.rb", "config/**/*.yml", "media/**/*.*"
    exposed_files "README.html", "LICENSE.txt"
    add_link "http://my_application.github.com", "My Application website"
    exclude_encoding # Applications that don't use advanced encoding (e.g. Japanese characters) can save build size with this.

    # Create a variety of releases, for all platforms.
    add_build :osx_app do
      url "com.github.my_application"
      wrapper "wrappers/gosu-mac-wrapper-0.7.41.tar.gz" # Assuming this is where you downloaded this file.
      icon "media/icon.icns"
      add_package :tar_gz
    end

    add_build :source do
      add_package :"7z"
    end

    # If building on a Windows machine, :windows_folder and/or :windows_installer are recommended.
    add_build :windows_folder do
      icon "media/icon.ico"
      executable_type :windows # Assuming you don't want it to run with a console window.
      add_package :exe # Windows self-extracting archive.
    end

    add_build :windows_installer do
      icon "media/icon.ico"
      start_menu_group "Spooner Games"
      readme "README.html" # User asked if they want to view readme after install.
      license "LICENSE.txt" # User asked to read this and confirm before installing.
      executable_type :windows # Assuming you don't want it to run with a console window.
      add_package :zip
    end

    # If unable to build on a Windows machine, :windows_wrapped is the only choice.
    add_build :windows_wrapped do
      wrapper "wrappers/ruby-1.9.3-p0-i386-mingw32.7z" # Assuming this is where you downloaded this file.
      executable_type :windows # Assuming you don't want it to run with a console window.
      exclude_tcl_tk # Assuming application doesn't use Tcl/Tk, then it can save a lot of size by using this.
      add_package :zip
    end

    add_deploy :local # Only deploy locally.
  end
  #>>>

Tasks created

Note: The windows:folder, windows:installer and windows:standalone will be created only if running on Windows. The windows:wrapped task will not be created if running on Windows.

The output from "rake -T" on Windows would be:

rake build                                # Build My Application 1.3.2
rake build:osx                            # Build all osx
rake build:osx:app                        # Build OS X app
rake build:source                         # Build source
rake build:windows                        # Build all windows
rake build:windows:folder                 # Build windows folder
rake build:windows:installer              # Build windows installer
rake deploy                               # Deploy My Application 1.3.2
rake deploy:osx:app:tar_gz:local          # local <= osx app .tar.gz
rake deploy:source:7z:local               # local <= source .7z
rake deploy:windows:folder:exe:local      # local <= windows folder .exe
rake deploy:windows:installer:zip:local   # local <= windows installer .zip
rake package                              # Package My Application 1.3.2
rake package:osx:app:tar_gz               # Package osx app .tar.gz
rake package:source:7z                    # Package source .7z
rake package:windows:folder:exe           # Package windows folder .exe
rake package:windows:installer:zip        # Package windows installer .zip

A variety of unlisted tasks are also created, that allow for more control, such as deploy:local (Deploy all packages locally), deploy:windows:folder (deploy all windows folder packages all destinations) or package:windows (Package all windows builds).

Build types supported

The project can build one or more release folders:

  • :source
    • Plain source folder, which can be used by anyone with Ruby already installed.
    • See {Releasy::Builders::Source}
  • :osx_app
    • OS X application bundle (.app) build, requiring a pre-made Ruby OS X wrapper. Note that this only contains binary gems for Gosu, TexPlay and Chipmunk, but will work with applications using any other source gems.
    • See {Releasy::Builders::OsxApp}
  • :windows_folder
    • A folder containing Ruby, application source files and an EXE to run them.
    • Available on Windows only.
    • See {Releasy::Builders::WindowsFolder}
  • :windows_wrapped
    • A folder containing Ruby, application source files and an EXE to run them, requiring a copy of a RubyInstaller archive.
    • Available on OS X and Linux only.
    • Creates larger release than other Windows build options.
    • See {Releasy::Builders::WindowsWrapped}
  • :windows_installer
    • A Windows installer.
    • Available on Windows only and requires InnoSetup to be installed.
    • See {Releasy::Builders::WindowsInstaller}
  • :windows_standalone
    • Standalone EXE file that self-extracts to a temporary directory, which is the default behaviour for Ocra.
    • Available on Windows only.
    • Slower startup than the other Windows build options (up to 2s slower).
    • See {Releasy::Builders::WindowsStandalone}

See {Releasy::Project#add_build}

Package types supported

Optionally, release folders can be packaged into an archive using one or more of:

  • :"7z"
    • 7Zip format (.7z - Best compression).
    • See {Releasy::Packagers::SevenZip}
  • :dmg
    • OS X self-extractor (.dmg - requires hdiutil to be installed, so only available on OS X).
    • Available on OS X only (hdiutils command required).
    • See {Releasy::Packagers::Dmg}
  • :exe
    • Windows self-extractor (.exe - Includes a 7z decompression module, so not efficient for small releases).
    • See {Releasy::Packagers::Exe}
  • :tar_bz2
    • Bzip2 tarball (.tar.bz2).
    • See {Releasy::Packagers::TarBzip2}
  • :tar_gz
    • Gzip tarball (.tar.gz).
    • See {Releasy::Packagers::TarGzip}
  • :zip
    • Standard zip format (.zip - Poor compression, but best compatibility).
    • See {Releasy::Packagers::Zip}

See {Releasy::Mixins::HasPackagers#add_package}

Deploy types supported

Optionally, packaged releases can be deployed using one or more of:

  • :local
    • Copy files locally, for example into a local web server or dropbox folder.
    • See {Releasy::Deployers::Local}
  • :rsync
    • Upload to remote server with rsync (requires 'rsync' command be installed).
    • See {Releasy::Deployers::Rsync}

See {Releasy::Project#add_deploy}

CLI Commands

Releasy also provides some supplementary commands:

$ releasy install-sfx [options]

Installs a copy of the Windows self-extractor in the local 7z installation, to allow use of the :exe archive format (it comes with the Windows version of 7z, so only need to use this command on OS X/Linux).

External Requirements

7-Zip

The 7z command must be installed on your system for Releasy to work:

  • OS X homebrew:

    $ brew install p7zip
    
  • Ubuntu/Debian:

    $ sudo apt-get install p7zip-full
    
  • Windows

    • 32-bit

      • 7z 32-bit executable included in gem.
    • 64-bit

      • 7z 32-bit executable included in gem, which will work fine.
      • If compression/decompression speed is really important to you, install the 64-bit .msi version of 7-Zip
  • Other OS

To build :windows_installer release (Windows only)

InnoSetup is used to create an installer for the application.

To build :windows_wrapped release (OS X/Linux)

RubyInstaller 7-ZIP archives for Ruby 1.8.7, 1.9.2 or 1.9.3. Used as a wrapper for a Windows release built on non-Windows systems.

To build :osx_app application bundle release (any platform)

libgosu app wrapper. Latest version of the OS X-compatible wrapper is "gosu-mac-wrapper-0.7.44.tar.gz" which uses Ruby 1.9.2 and includes some binary gems: Gosu, Chipmunk and TexPlay.

Warning: "gosu-mac-0.7.44.tar.gz" is NOT the complete OS X app wrapper, but rather just the Gosu gem pre-compiled for OS X!

Similar tools

  • Ocra: Builds standalone Windows executable or a Windows installer. Releasy uses Ocra, but greatly extends its capabilities.

    • Advantages: Creating a standalone executable requires just a simple command.
    • Disadvantages: Can't build except on Windows; standalone executable slow to load; more difficult to create an installer.
  • Crate: Cross-platform executable builder.

    • Advantages: Probably faster to load, since all source files are stored in an SQLite database; works anywhere Ruby can be compiled.
    • Disadvantages: Requires C compiler; not compatible with Ruby 1.9; may not be supported any more.
  • exerb-mingw

    • Advantages: Unsure.
    • Disadvantages: Unsure; no English documentation; may not be supported any more.
  • rubyscript2exe: Builds a standalone Windows executable.

    • Advantages: None.
    • Disadvantages: Not compatible with Ruby 1.9; may not be supported any more.

Credits

  • Thanks to jlnr for creating "RubyGosu App.app", an OS X application bundle used to wrap application code.
  • Thanks to larsh for the Ocra gem, which is used for generating Win32 executables.
  • Thanks to jlnr, SukiSan and shawn42 for help testing on OS X; without you I would have been screwed!
  • Thanks to shawn42 and everyone at #gosu and #ruby (irc.freenode.org) for suggestions on how to improve the API.
  • Thanks to kyrylo for coming up with the name, Releasy!

Third Party Assets included

  • bin/7z.sfx - Windows 7-ZIP self-extractor module, which can be installed using releasy install-sfx [License: GNU LGPL]
  • bin/7za.exe - Windows 7-ZIP CLI executable.
Something went wrong with that request. Please try again.