= Installing wxRuby wxRuby is fully supported on Ruby 1.8 and Ruby 1.9.1. There are two ways of installing wxRuby2: * Using Rubygems to install a precompiled binary gem * Obtaining the sources and compiling wxRuby yourself For most users (especially on Windows and OS X), using rubygems will be most convenient, and is recommended. Compiling may be needed on systems which have very varied configurations (in particular, Linux). You'll also need to compile yourself if you want to use the latest development code, rather than a numbered release. = Installing wxRuby using Rubygems On Windows and OS X, the only normal prerequisite is Ruby itself and rubygems. On Linux, you will need your distro's wx library installed. See below for platform-specific information. == Temporary instructions for gem installation As of February 2009, Rubygems has a serious bug which means that the latest version of specific gems are not correctly offered by the automatic installation procedure. This affects a variety of gems and ruby and rubygems versions. Please follow these temporary instructions until this is resolved: Download the correct gem file for your platform from the wxRuby download page: http://rubyforge.org/frs/?group_id=35 Gems for 1.8 are named: wxruby-[version]-[processor]-[os].gem Gems for 1.9 are named: wxruby-ruby19-[version]-[processor]-[os].gem Choose the latest version available for your processor and operating system: mswin32 or mingw32 for Windows, darwin for for OS X, linux for Linux. Save the file to your local hard drive. Open a command prompt or terminal, go to the directory where the gem file is saved, and do: gem install For example: gem install wxruby-1.9.10-x86-mswin32-60.gem On Linux and OS X, you may need to run this command as a privileged user, eg sudo gem install == Proper instructions for gem installation To install wxRuby using Rubygems, open a command prompt and type: gem install wxruby # Ruby 1.8 gem install wxruby-ruby19 # Ruby 1.9 If you are on Linux or OS X, you will likely need to run this as a privileged user, something like: sudo gem install wxruby Wait whilst rubygems updates its gem list. You will then be offered a choice of gems to install. Choose the most up-to-date one available for your platform. Rubygems will download and install the desired gem. On Linux, you should also install your distro's wxwidgets 2.8 libraries. On Windows and OS X, the gem contains everything needed to create and run wxRuby applications; you're ready to go. === Gem Installation Notes - Microsoft Windows * x86-mswin32 gems are for ruby on Windows NT/2000/XP/Vista on Intel-32, built with the Microsoft compiler. This includes current releases of the One-Click Installer. * x86-mingw gems are compatible with ruby built on Windows using the MingW compiler * If using NT or 2000, you may need to install the free library gdiplus.dll in your Windows/system32 directory. * If using a recent fresh install of NT, 2000 or XP, you may need to install the dll msvcp71.dll. This can be downloaded for free. * To get native XP-style widgets on XP you need to create a manifest.exe file for ruby; see here for more information: http://rubyonwindows.blogspot.com/2007/10/windows-xp-visual-style-controls-with.html * Unfortunately, wxRuby2 does not currently work on Windows 3.1, 98 or Me, as these do not have adequate unicode support. The old wxruby-0.6.0 release should work (to the best of its limited abilities) on these platforms. === Gem Installation Notes - OS X * Gems are provided as single universal binary for both Intel and PowerPC Apple machines * wxRuby binary gems are compatible with versions 10.4 (Tiger) and 10.5 (Leopard) === Gem Installation Notes - Linux * The wxRuby gems for Linux are intended to work with your system's existing packages and libraries. Therefore, you should install the wxwidgets-2.8 package(s) for your system, eg libwx-2.8 * The gems are built on recent versions of Ubuntu; due to the wide variation between the configuration of different distros, they may not work correctly with other distributions and versions. If you experience errors after installing the gem, you will need to compile your own version of wxRuby. * On some systems libselinux1-related shutdown crashs are reported with wxRuby. On Ubuntu Hardy, this workaround fixed it: http://www.libavg.de/wiki/index.php/Libavg_on_Ubuntu#8.04_known_issue = Compiling wxRuby from Source The remainder of this document covers compiling ruby from source. Compiling wxRuby is recommended if you wish to use the latest development version, or if you want to work with a specific configuration of wxWidgets - for example, that provided by a Linux distro. You may also need to compile wxRuby if a binary gem is not available for your platform. == Compilation prerequisites * A C++ compiler: MSVC or MingW for Windows; gcc (g++) for Linux and OS X * A recent version of SWIG, especially for Ruby 1.9. * rake * A compiled wxWidgets library, either built yourself or installed from via a package manager wxWidgets has a huge range of compile-time options, and wxRuby tries to support as many of these as possible. In particular, both debug and release builds are supported; a debug build is recommended if you're interested in working on wxRuby. On windows, only static builds are supported; on Linux and OS X, either statically or dynamically linked libraries can be used. wxRuby will skip several optional features if they are not supported by your wxWidgets library; these include StyledTextCtrl, GraphicsContext and OpenGL classes. == Obtaining wxRuby source code Tarballs containing the wxRuby source for released versions can be downloaded from the wxRuby Rubyforge pages: http://rubyforge.org/frs/?group_id=35 If you wish to use the latest development code, it's hosted in Subversion at rubyforge.org. Note that this code may be incomplete or buggy. To check it out do svn co svn://rubyforge.org/var/svn/wxruby/trunk/wxruby2 == Setting build options If you're compiling on Windows, you *must* set an environment variable to indicate where the WxWidgets libraries and header files can be found: set WXWIN=C:/path/to/wxMSW-2.8.9 The path should be the top-level directory of the unpacked wxWidgets tarball; it's recommended that the path does not contain spaces. If you have multiple parallel versions of wxWidgets installed, you may influence which build is selected by setting or unsetting the environment variables WXRUBY_DEBUG, WXRUBY_RELEASE, WXRUBY_STATIC and WXRUBY_DYNAMIC. eg export WXRUBY_DEBUG=1 Forces wxRuby to be built against a -debug version of wxWidgets. Lastly, you may specifically exclude certain classes; this is most often useful if a particular class is causing problems: export WXRUBY_EXCLUDE=ThisClass,ThatClass == Running the compile task From the top-level directory of the unpacked or downloaded wxRuby directory, just start the rake build with the command: rake There is no ./configure step, nor do you need to run ruby extconf.rb. wxRuby has approaching 300 classes to generate, compile and link, so the process may take some time. == Using a compiled library To run a wxRuby program using the newly compiled library, you can run ruby with the -I flag pointing to the lib directory. For example, a quick test of a newly compiled library might be: ruby -Ilib samples/minimal/minimal.rb == Installing a compiled library Rubygems has emerged as the standard for managing user ruby libraries, so you may wish to create a gem from your compiled code and install it. To create a gem, do: rake gem This will create a gem file, which you can install as above. If you do not wish to use Rubygems, you can also do rake install This will install wxRuby into your site_ruby directories. As with gem commands, you may need to be root do this. Note that as Rubygems has become the standard installation method for Ruby libraries, the 'install' task is no longer regularly maintained and tested. = Porting to other platforms The instructions above cover all the platforms that are in current use for wxRuby. It should however be possible to use wxRuby on any platform supported by wxWidgets and Ruby: http://wiki.wxwidgets.org/Supported_Platforms Platform-dependent rakefiles are used to set up compiler-specific settings. The following platforms are currently fully supported: Mac OSX (gcc): rakemacosx.rb Linux (GTK2 + gcc): rakelinux.rb Windows (shared): rakewindows.rb Windows (MSVC): rakemswin.rb Windows (MingW): rakemingw.rb For other platforms, you will need to create or edit the appropriate platform-dependent rake file if your system is not yet supported, or if it is unusual. These files are found in the rake subdirectory, for example: NetBSD: rakenetbsd.rb The existing rake files should provide a starting point. When editing a platform-dependent rakefile, you might merely need to set one or more of the following variables: $extra_cppflags $extra_ldflags $extra_objs $extra_libs