Skip to content

Installation and your first window

This lesson gets wxRuby3 installed and running on your machine. The process has a few more steps than a typical gem install — wxRuby3 wraps a C++ toolkit, so there is a build step involved. This lesson walks through it on each platform and makes sure you know what a working installation looks like before moving on.

Prerequisites

Ruby

wxRuby3 requires Ruby 3.1 or later. Check your version:

1

ruby --version

If you are managing Ruby versions with rbenv, mise, or asdf, make sure the version is active before installing the gem. wxRuby3’s native extensions are compiled against the Ruby version that was active at install time — mixing versions later causes confusing errors.

Platform prerequisites

macOS

You need Xcode Command Line Tools:

1

xcode-select --install

If you have Homebrew, that is sufficient — it pulls in the tools wxRuby3 needs. No additional libraries are required on macOS; the setup process uses the system’s built-in WebKit and Cocoa frameworks.

Installing the gem 

1

gem install wxruby3

On macOS and Linux, this installs the gem but does not yet build the native extensions. That is the next step.

On Windows with RubyInstaller, the binary gem installs completely here and you can skip the setup step.

Building the native extensions (macOS and Linux) 

1

wxruby setup

This command compiles wxRuby3’s native extension libraries against your platform’s wxWidgets installation. Depending on your machine and whether wxWidgets needs to be built from source, this can take anywhere from two minutes to twenty.

You will see output as the build progresses. If it fails, the error is almost always a missing system library — the message will name the missing dependency.

To run setup without interactive prompts (useful in CI or scripted environments):

1

wxruby setup --autoinstall

Verifying the installation 

1

wxruby check

A working installation exits silently. If something is wrong, this command tells you what is missing.

For a more thorough check, run the test suite:

1

wxruby test

This takes a few minutes but confirms that the native extensions are working correctly. You do not need to run this every time — once after initial setup is enough.

Exploring the bundled sampler

wxRuby3 ships with dozens of working example applications. Before writing your own code, it is worth spending a few minutes here:

1

wxruby sampler

This opens a GUI window listing all bundled samples by category. Double-click any sample to run it. You will see menus, toolbars, custom drawing, grids, trees, dialogs — the full range of what wxRuby3 can do. We return to the sampler in the next lesson with more guidance on how to read the code.

Your first window

Create a file called hello.rb:

1
2
3
4
5
6

require 'wx'

Wx::App.run do
  frame = Wx::Frame.new(nil, title: 'Hello wxRuby3!', size: [400, 300])
  frame.show
end

Run it:

1

ruby hello.rb

A native, empty window should appear. That is a complete wxRuby3 application — an event loop is running, the window is responding to resize and close events, and the process will exit cleanly when you close the window.

A more structured first app

The one-liner above works, but real wxRuby3 apps use a class for the frame. Here is the pattern you will use throughout this series:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

require 'wx'

class HelloFrame < Wx::Frame
  def initialize
    super(nil, title: 'Hello wxRuby3!', size: [400, 300])

    panel  = Wx::Panel.new(self)
    label  = Wx::StaticText.new(panel, label: 'Hello from wxRuby3!')
    button = Wx::Button.new(panel, label: 'Click me')

    sizer = Wx::VBoxSizer.new
    sizer.add(label,  0, Wx::ALL | Wx::CENTRE, 20)
    sizer.add(button, 0, Wx::ALL | Wx::CENTRE, 10)
    panel.set_sizer(sizer)

    evt_button(button.get_id) { on_click }

    centre
  end

  private

  def on_click
    Wx::message_box('Button clicked!', 'Hello', Wx::OK | Wx::ICON_INFORMATION)
  end
end

Wx::App.run { HelloFrame.new.show }

Run this and you have a window with a label, a button, and a working click handler that shows a native message dialog.

This is the skeleton of every wxRuby3 app you will write:

  • A class inheriting from Wx::Frame
  • initialize calls super with the window title and size, then builds the widget tree
  • A Wx::Panel immediately inside the frame, widgets inside the panel
  • A sizer managing the layout (covered properly in Module 2)
  • evt_* methods registering handlers in initialize
  • Handler methods defined privately

Save this file. You will modify it in the sampler lesson, and it is useful to have a working skeleton to hand throughout the series.

If something goes wrong

require 'wx' fails with a load error The gem is installed but the native extensions are not built. Run wxruby setup.

wxruby: command not found The gem’s executables are not on your PATH. Run gem environment to find the bin directory and add it to your shell profile. With rbenv or mise, try rbenv rehash or mise reshim.

The window appears but looks wrong (wrong colours, misaligned controls) You are likely placing controls directly inside the frame rather than inside a panel. Always use Wx::Panel.new(self) and parent your controls to the panel.

Build fails on Linux with a missing header The wxWidgets development libraries are not installed. Return to the platform prerequisites section above and install the listed packages for your distribution.

Previous: The mental model shift | Next: Exploring the sampler

The mental model shiftExploring the sampler