Wayne Vucenic edited this page Sep 8, 2016 · 68 revisions

General FAQs

DevKit self-extracting executable (SFX) FAQs

DevKit Installer FAQs

GUIs and the RubyInstaller FAQs

Development and Contributing FAQs


Q: What are the goals of this project? Why does this project exist?

A: The RubyInstaller project aims to provide developers working on Windows systems with a quick and easy way to begin developing with Ruby using an MRI-based (Matz’s Ruby Implementation) environment while enabling enhancements through Ruby’s standard RubyGems packaging system.

Specifically, the goals of the RubyInstaller are:

  1. Provide a easy to use Windows installer for quickly and painlessly installing a fully functioning baseline MRI Ruby environment on Windows platforms.
  2. Provide an optional Development Kit for those interested in building mswin32-compatible Ruby extensions natively on Windows platforms using a MSys/MinGW based toolchain.
  3. Provide a build environment via this project and complementary projects like rake-compiler to help developers easily build Ruby and Ruby C extensions from source code.
  4. Add value to the growing community of Windows-based Ruby developers by providing a place that summarizes the hard won lessons and issues with building Ruby and Ruby C extensions natively on Windows.

Q: What versions of Windows does RubyInstaller currently support?

A: Currently RubyInstaller explicitly supports (Windows XP) not working as of Ruby 2.2.2), Windows Vista, Windows 7, and Windows 8 in both 32 and 64-bit flavors. By “explicit” we mean that we accept bugs discovered on those versions, we perform testing of the installer on those versions, and we use code that supports those versions. This doesn’t mean that RubyInstaller may not work on other Windows flavors, it just means that we’ve had to focus our resources on supporting the more mainstream Windows versions.

Q: I understand the project goals, but why can’t I simply download the latest MRI binary distributions for Windows from ruby-lang.org?

A: The binary packages for Windows found on ruby-lang.org lack several key components, such as OpenSSL, Zlib and Readline, which results in a broken experience for users trying install these binary distributions out-of-the-box. To compound the issue, other extensions are built-in, but lack essential bindings such as Tk and gdbm.

Locating and installing the correct versions of these missing components can be tricky; RubyInstaller seeks to alleviate these difficulties and make the installation process dead-simple by providing everything you need to get started in one straightforward installation package.

Q: How should my Ruby app determine if it’s running on Windows?

require 'rbconfig'
if RbConfig::CONFIG['host_os'] =~ /mingw|mswin/
  # running on Windows

Q: Should I install to C:\Program Files?

A: No.

Q: Using the RubyInstaller, can I install Ruby 1.8 and 1.9 at the same time?

A: Yes. By using the RubyInstaller, Ruby 1.8 will be installed by default to C:\Ruby, while 1.9 will be installed to C:\Ruby19. This is by design as Ruby 1.8 and 1.9 offer a different API that may interfere with some RubyGems.

Q: How do I perform a silent install with the RubyInstaller?

A: The RubyInstaller currently uses Inno Setup which allows two levels of silent installation (silent with just an install progress window, or very silent without even an install progress window) to be selected using either the /silent or /verysilent command line options.

When performing silent installations, you often want to specify where to install the Ruby environment and whether the RubyInstaller should associate .RB/.RBW files and update your PATH environment variable to use the newly installed Ruby.

While the Inno Setup Help provides the details, an example shows how easy it is:

# silent install to default dir with no file associations nor PATH update
c:\>rubyinstaller.exe /silent

# silent install to custom dir with no file associations nor PATH update
c:\>rubyinstaller.exe /silent /dir="e:\my_test_ruby"

# silent install to default dir with private Tcl/Tk library installation
c:\>rubyinstaller.exe /silent /tasks=addtk

# use Japanese installer to silently install to default dir with private Tcl/Tk,
# file associations, and PATH update
c:\>rubyinstaller.exe /silent /lang=ja /tasks="addtk,assocfiles,modpath"
# very silent install to default dir with file associations but no PATH update
c:\>rubyinstaller.exe /verysilent /tasks=assocfiles

# very silent install to custom dir with file associations and PATH update
c:\>rubyinstaller.exe /verysilent /dir="d:\rubyABC" /tasks="assocfiles,modpath"

Q: If I install both versions, is there some graceful way of selecting which version is active at a given time (e.g., which ruby.exe is invoked, which irb.bat is called, etc.)?

A: Pik used to be recommended for this, but it’s no longer maintained. Uru is the current recommendation.

Q: Why are the installers so small?

A: Because the installers contain just the baseline Ruby environment, the RubyGems package system, key DLLs required to ensure a usable baseline Ruby installation, and important Ruby documentation. This baseline Ruby installation enables you to quickly begin developing in Ruby and to quickly begin using existing Ruby applications while enabling you to customize your Ruby environment for your unique needs.

Q: When I uninstalled the RubyInstaller, I saw that there were some leftover files in the installation directory. Did the RubyInstaller uninstall incorrectly? Did I do something wrong? Should I file a bug?

A: Not to worry, you did nothing wrong and there’s no need to file a bug report. The RubyInstaller uninstalled correctly as we built the RubyInstaller to uninstall only the files it originally installed. Any leftover files in the installation directory are most likely due to customizations you made to your RubyInstaller-provided Ruby environment. We do not want the RubyInstaller assuming it should delete any of your customizations.

For example, imagine that you’ve modified your Ruby installation with a few of your favorite RubyGems via gem install rake citrus sinatra haml nokogiri sequel and you’ve also created a super cool executable Ruby script that automates away much of your daily monkey work. You’ve also just found out that a new version of the RubyInstaller is available with the latest and greatest Ruby bug fixes and you’d like to upgrade it, but do not want to go through the hassle of reinstalling all of your RubyGems or losing your super cool Ruby automation script.

Since the RubyInstaller does not blindly delete everything in the RubyInstaller install directory, all of your RubyGems and custom files that you configured for your Ruby environment with remain after the RubyInstaller uninstalls. The RubyInstaller will uninstall itself, but not your customizations. We think you would be very unhappy if the RubyInstaller assumed it could delete itself and everything you worked so hard to customize. We believe you’re the only one who knows best when deciding how you to manage your Ruby customizations.

However, if you discover that RubyInstaller is not behaving as described, please let us know via the mailing list or the bug tracker listed later in the FAQ.

Q: What happened to all those nice things that the original One-Click Installer (OCI) bundled in for us?

A: The not-so-short answer is that while many of the original packages are no longer pre-installed by the new RubyInstaller, we believe we’ve integrated just the right amount of core features while enabling you to easily add additional capabilities that you may need by utilizing the proven RubyGems packaging system. As always, there’s a longer answer :)

Q: OK, I get the short answer. But I really want to know why on earth you didn’t bundle all the goodies that the original OCI included?

A: This version of Ruby has been built with MinGW (GCC), not the 12 year old compiler in Visual Studio version (VC6) used by the original One-Click Installer.

In the original installers, lot of gems and packages were bundled. Some of those packages have not been updated in years, some of the packages do not appear to regularly maintained, and some of the packages lack the tests and testing tools needed to ensure they work as expected with this version of Ruby.

Instead of investing the RubyInstaller Team’s limited time on fixing those packages, we decided to focus on improving the overall user experience on Windows-based systems by providing a rock-solid Ruby baseline installation from which you can build upon based upon your unique needs.

We acknowledge that some gems will not work, and some others will not install. That’s why we provide a Development Kit (DevKit) to ease the process of rebuilding the gems for your Ruby installation. The DevKit contains the needed tools to compile or successfully install gems that are not ready for this version of Ruby.

The Development Kit can be downloaded from RubyInstaller Downloads

Q: Where is SciTE editor that was bundled before? I want it back!

A: Like you, some users would like RubyInstaller to bundle SciTE, other users might want some other editor, and still others no editor at all. The approach of the RubyInstaller project is to not dictate any preference over users or usage, giving users the freedom to choose what tool they want to work with.

As RubyInstaller do not try to take over user’s installation, we don’t want to take over user’s preference for editors. You can refer to Windows Friendly Editors for instructions on how to use RubyInstaller with different editors, including SciTE.

If you want to read Luis Lavena’s personal statement about this decision, please read this message at RubyInstaller Google group.

Q: Got it, but what if I want those gems to work right now?

A: If those gems don’t work out of the box with DevKit installed, please contact the gem author and make them aware of this compatibility issue with their gem.

DevKit self-extracting executable (SFX)

Q: How do I uninstall the legacy DevKit?

A: The legacy Devkit devkit-3.4.5r3-20091110.7z extracted gcc.bat, make.bat, sh.bat batch helper scripts to a specific Ruby installation into the Ruby’s <RUBY_INSTALL_DIR>\bin and its core files into <RUBY_INSTALL_DIR>\devkit. To uninstall the legacy DevKit, simply delete the batch helper scripts and the <RUBY_INSTALL_DIR>\devkit subdirectory and double check that your PATH environment variable does not contain any references to what you deleted.

Q: How do I upgrade the SFX DevKit when a new version becomes available?

A: The self-extracting executable (SFX) DevKit version does not require one to separately download the 7-Zip tool in order to install it. Simply download the executable, double-click, choose an install directory and extract. While you’ll need to do a bit of configuration, installation is straight forward. However, as the SFX is not a full-featured installer, upgrading the SFX DevKit to a newer version requires some manual work, but not too much. NOTE: the SFX is really a 7-Zip archive with a bit of embedded magic. If you already have 7-Zip installed, you can simply right-click it and extract it’s contents as you would a normal 7z archive.

A typical update can be as simple as:

1. Open up the directory where you originally installed the DevKit. Let’s call that <DEVKIT_INSTALL_DIR>
2. Delete all the <DEVKIT_INSTALL_DIR> subdirectories and files except for config.yml. If you’ve made any customizations to the MSYS shell you may also want to keep files in the etc and home subdirectories.
3. Extract the new SFX DevKit into the same <DEVKIT_INSTALL_DIR> that you just cleaned up.
4. Review your config.yml file to ensure it contains the root directories of all the installed Rubies you want enhanced to use the DevKit.
5. From a Command Prompt, cd into the <DEVKIT_INSTALL_DIR> directory and run ruby dk.rb install --force. This will cause all your installed Rubies listed in config.yml to use the updated SFX DevKit when building native gems and update the DevKit’s helper scripts (devkit.rb and operating_system.rb) with any new functionality. For safety, the original helper scripts are timestamp archived beside the new helper scripts. It’s always a good idea to review the two versions (and potentially make modifications) to ensure configuration specific to your system still works as expected.

DevKit Installer

Q: I love the RubyInstaller, but where’s the DevKit installer?

A: Glad to hear you like it! We’re started the work to create a DevKit installer that’s just as easy to use as the RubyInstaller. However, there hasn’t been much demand for the DevKit installer. However, if you’d like to help speed things along, drop by the RubyInstaller Google Group and let us know how you’d like to help.

GUIs and the RubyInstaller

Q: I see the RubyInstaller can optionally install the Tcl/Tk GUI toolkit. Tell me more!

A: Both the .exe installers and .7z archives include the libraries required to develop GUI applications in Ruby using the integrated Tcl/Tk toolkit. The Tcl/Tk toolkit is integrated with the RubyInstaller in such a way so as to not conflict with existing Tcl/Tk installations (e.g. – ActiveState’s ActiveTcl) you may have installed on your system.

If you install Ruby using the .exe installers, the Tcl/Tk installation is optional. Simply opt-in by selecting a checkbox in the GUI or specify the addtk task if installing silently from the command line. If you don’t want Tcl/Tk support, there’s nothing extra you need to do.

If you install Ruby by extracting from the .7z archives, Tcl/Tk support is already integrated and ready to use without further configuration from you.

Q: Why was Tcl/Tk selected as the GUI toolkit to be bundled with the RubyInstaller?

A: in process

Q: Will the RubyInstaller’s Tcl/Tk conflict with an existing Tcl/Tk?

A: No. The (optional) Tcl/Tk support is private to the RubyInstaller and will not conflict with an existing Tcl/Tk installation you may already have installed. If the RubyInstaller’s private copy does conflict, we’ve overlooked something and it’s a bug that must be fixed. Please let us know ASAP if this ever happens.

Q: Can I use an existing Tcl/Tk installation with the RubyInstaller Ruby?

A: No. in process

Q: Where can I learn more about building GUIs in Ruby with Tcl/Tk?

A: While Google is your friend for this one, this Ruby Tk tutorial is a fantastic first step. As the installers and archives include the required Tcl/Tk libraries and Ruby’s Tk extension, you can skip the tutorial’s installation section and jump directly to the examples.

Q: Can I build GUIs in Ruby with GTK+?

A: Absolutely. The Ruby-GNOME2 project provides a 1.8/1.9 native Rubygem for RubyInstaller environments that includes all required dependencies. To get started simply type gem install gtk2 and start building your next GUI in Ruby! Check out their tutorial for more info.

Development and Contributing

Q: How should I configure MSysGit before contributing or trying to use the project build recipes?

A: Ensure your global configuration contains at least the following settings, ensure cygwin is not on your PATH, and no strange variables in your .bashrc or .bash_profile hidden in your HOME directory.

C:\>git config --global --list

Q: How do I build a GDB-friendly Ruby with the build recipes?

A: By default, all RubyInstaller downloads are already GDB-friendly as they are built with the -g option. For performance reasons they’re also optimized with the -O3 option that can interfere with debugging. For intense debugging sessions, your Ruby should be built with -ggdb3 -O0 and the easiest way to do this is to override the default build configuration by placing a .rb file in the override subdirectory of your RubyInstaller clone similar to the following. Finally, run something similar to rake ruby19 debug_build=1 and look in the sandbox/ruby19_mingw subdir for your new GDB-friendlier RubyInstaller build.

# file: override/debug_build.rb
if ENV['DEBUG_BUILD'] then
  puts '[INFO] Generating debug optimized build...'

  # enable debug 1.9.x builds
  RubyInstaller::Ruby19.configure_options << "optflags='-O0'"
  RubyInstaller::Ruby19.configure_options << "debugflags='-ggdb3'"

Q: I’ve tried to contact the gem author and he/she said doesn’t have a Windows-based system on which to build a binary gem for me.

A: That’s understandable. Not all developers have the means to afford a Windows license, and even among those who do, not all have (or are willing to take) the time to set up a virtual machine and develop Windows binaries for their gems.

For that purpose, the RubyInstaller Team created the “rake-compiler” tool available from the following sites:

rake-compiler on RubyForge

rake-compiler on GitHub

With this tool the gem authors can compile and build gems for Windows users from Linux or Mac OSX operating systems.

There are already plenty of other gem authors using rake-compiler, so please give the following link to the gem author so they can take a look to those implementations for examples of how they might use rake-compiler to update their gems.


Q: Now that Microsoft is providing its free Visual C++ Express editions and including build tools such as cl, link, nmake, etc. as part of the Windows SDK (as of mid-2009). Why can’t I just download the MRI binary and Visual C++ Express and start developing? Why would I want a MinGW-based implementation?

A: Unfortunately, a lot of popular Ruby projects out there still assume that the underlying operating system is going to be a GNU-ish one such as provided by MinGW, so this is still the way to go if you need stable, well-supported code. But if you are a trail-blazing sort and like getting your hands dirty, your help on the “mswin” side of things could make a big difference!

Q: Cool, I’m going to test it! What do I do if I find a bug?

A: Please submit any bugs you find to the Issues tracker at GitHub:

RubyInstaller issues tracker

Q: Excellent! What if I want to contribute to the project or just have a suggestion?

A: We would love to hear from you! Documentation updates, patches, tasty graphics creations, how you think we can improve the process, and anything else you would like to contribute are all really appreciated, and requested :)

First, take a look at our How to Contribute page, then join us at our rubyinstaller Google Group:


Please introduce yourself and share with us what you would like to see improved, implemented or fixed. We are a friendly bunch of users and developers who are deeply passionate about running Ruby on Windows :-)

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.