wxruby3 0.9.5 → 0.9.8

data/README.md

@@ -96,11 +96,11 @@ of these products.
 
 Currently the following are fully supported:
 
-| Platform                                                                   | Ruby version(s)                             | wxWidgets version(s) |
-|----------------------------------------------------------------------------|---------------------------------------------|----------------------|
-| Windows 10 (tested)<br>(most likely also Windows 11)                       | Ruby >= 2.5<br>(RubyInstaller MSYS2-DevKit) | wxWidgets >= 3.2     |
-| Linux (tested; any AMD-64 distribution)<br>(most likely also i686 and ARM) | Ruby >= 2.5                                 | wxWidgets >= 3.2     |
-| MacOS >= 10.10 using Cocoa (tested on AMD-64 and ARM64 M2 Chip)            | Ruby >= 2.5                                 | wxWidgets >= 3.2     |
+| Platform                                                                                                                           | Ruby version(s)                                     | wxWidgets version(s) |
+|------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|----------------------|
+| Windows 10 (tested)<br>(most likely also Windows 11)                                                                               | Ruby >= 2.5<br>(RubyInstaller MSYS2-DevKit)         | wxWidgets >= 3.2     |
+| Linux (tested; all major AMD64 and ARM64 distributions: Ubuntu, Debian, Fedora, OpenSuSE and ArchLinux)<br>(most likely also i686) | Ruby >= 2.5                                         | wxWidgets >= 3.2     |
+| MacOS >= 10.10 using Cocoa (tested on AMD64 and ARM64 M1/M2 Chip)                                                                  | Ruby >= 2.5 (MacPorts, Homebrew, ruby-install, RVM) | wxWidgets >= 3.2     |
 
 Support for other platforms is not being actively developed at present,
 but patches are welcome. It is likely to be much simpler to get wxRuby
@@ -109,32 +109,49 @@ on legacy systems (eg Windows 98, Mac OS 9).
 
 ### How can I install wxRuby3?
 
-wxRuby3 is distributed as a Ruby gem on [RubyGems](https://rubygems.org).<br>
-Apart from a regular source-only version of the gem there is also a binary gem version for Windows 10 provided (for the 
-latest stable Ruby version at the time of publishing) which includes an embedded wxWidgets installation (also latest 
-stable version). 
+wxRuby3 is distributed as a Ruby gem on [RubyGems](https://rubygems.org). This gem can also be downloaded from the release 
+assets on [Github](https://github.com/mcorino/wxRuby3/releases).
 
-Installing the binary gem version on Windows requires no additional software to be installed except for a supported 
-version of the Ruby interpreter.<br>
-To install the source-only gem the following software is required:
+The wxRuby3 gem provides a **worry-free** installation procedure for all supported platforms.  
 
-| Sofware                                       | Notes                                                                                                                                                                                                                           |
-|-----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Ruby                                          | A supported version of the Ruby interpreter needs to be installed.                                                                                                                                                              |
-| C++ compiler<br>(incl. dev tools like `make`) | On linux a recent version of the GNU C++ compiler (with c++-14 support) needs to be installed<br>On Windows the RubyInstaller MSYS2-Devkit needs to be installed<br>On MacOS XCode with commandline tools needs to be installed |
-| Git version control toolkit                   |                                                                                                                                                                                                                                 |
-| SWIG >= 3.0.12                                | On MacOS install with Homebrew                                                                                                                                                                                                  |
-| Doxygen (>= 1.9.1)                            | On MacOS install with Homebrew                                                                                                                                                                                                  |
-| wxWidgets >= 3.2 (*OPTIONAL*)                 | On Linux most distributions provide system installable (development) packages for wxWidgets providing a supported version.<br>Alternatively you can fairly easily install your own preferred version manually.                  |    
+Installing the gem requires no additional installation steps and/or additional software to be installed except for a 
+supported version of the Ruby interpreter. So the following command is all it takes to install: 
 
-See the [INSTALL](INSTALL.md) document for more details.
+```shell
+gem install wxruby3
+```
 
-In case the prerequisites above are met the (source-only or binary) gem can be installed executing the following command:
+The wxRuby3 installation procedure will check the availability of a, prebuilt, binary package matching the platform
+being installed on and if found will download and install that package resulting in a ready-to-run wxRuby3 installation.<br>
+If no matching package is found the installation reverts to a source installation which will require an additional setup
+step to finalize the wxRuby3 installation by executing the following command:
 
 ```shell
-gem install wxruby3
+wxruby setup
 ```
 
+This last command is a fully automated setup procedure provided by the wxRuby3 **CLI** installed with the gem. This 
+procedure (by default) will analyze your system and install (after asking your consent) any missing software 
+requirements and build the wxRuby3 extension libraries (including a embedded copy of wxWidgets if necessary). It may 
+take quite a while depending on your system but you can mostly sit back and relax.
+
+> **NOTE**<br>
+> A source based installation requires the availability of the Ruby development headers. User installed Rubies in most cases
+> will already include those but (especially on Linux) system installed Rubies may require having an additional '-dev/-devel'
+> package installed (although actually you may already have needed those to install the gems that the wxRuby3 gem depends 
+> on like the nokogiri gem).
+
+The wxRuby3 CLI also provides a 'check' command with which the runtime status of the wxRuby3 installation can be checked
+at any time. By default running `wxruby check` will display a message reporting the runtime and suggestions on finalizing
+the installation if not finalized yet. No message is displayed if wxRuby3 is ready to run. Run `wxruby check -h` for 
+details concerning this command. 
+
+A selection of (prebuilt) binary packages is provided as release assets on [Github](https://github.com/mcorino/wxRuby3/releases).
+See the [INSTALL](INSTALL.md#binary-packages) document for more details.
+
+This install procedure can of course be tweaked and customized with commandline arguments.
+See the [INSTALL](INSTALL.md) document for more details.
+
 ### Where can I ask a question, or report a bug?
 
 Use GitHUb Issues.

data/ext/mkrf_conf_ext.rb

@@ -0,0 +1,68 @@
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+
+###
+# wxRuby3 extension configuration file for gems
+###
+
+OPTIONS = {
+}
+
+until ARGV.empty?
+  switch = ARGV.shift
+  case switch
+  when /^prebuilt=(none|only)$/
+    OPTIONS[:prebuilt] = $1 == 'only'
+  when /^package=(.+)$/
+    OPTIONS[:package] = $1
+  when 'help'
+    puts <<~__INFO_TXT
+      wxRuby3 extension build script
+
+      Usage: gem install wxruby3 -- help OR gem install wxruby3 [-- options [...]]
+
+        options:
+
+        prebuilt=OPT    Specifies to either require (OPT == 'only') or avoid (OPT == 'none') installing prebuilt 
+                        binary packages. If not specified installing a prebuilt package will be attempted reverting 
+                        to source install if none found.
+
+        package=URL     Specifies the http(s) url or absolute path to the prebuilt binary package to install.
+                        Implies 'prebuilt=only'.
+
+        help            Show this message.
+      __INFO_TXT
+    puts
+    exit(1)
+  else
+    $stderr.puts "ERROR: Invalid option [#{switch}] for wxRuby3 extension build script."
+    exit(1)
+  end
+end
+
+task_args = ''
+unless OPTIONS[:prebuilt].nil?
+  task_args << "'#{(OPTIONS[:prebuilt] ? '--prebuilt' : '--no-prebuilt')}'"
+end
+if OPTIONS[:package]
+  task_args << ', ' unless task_args.empty?
+  pkg = RUBY_PLATFORM =~ /mingw/ ? OPTIONS[:package].gsub('\\', '/') : OPTIONS[:package] # make sure the path is URI compatible
+  task_args << "'--package', " << "'#{pkg}'"
+end
+
+# generate new rakefile with appropriate default task (calls actual task in rakelib)
+File.open('../Rakefile', 'w') do |f|
+  f.puts <<EOF__
+###
+# wxRuby3 rake file
+# Copyright (c) M.J.N. Corino, The Netherlands
+###
+
+unless File.file?(File.join('lib', 'wx', 'wxruby_core.so'))
+  task :default do
+    Rake::Task['wxruby:gem:install'].invoke(#{task_args})
+  end
+end
+EOF__
+end

data/lib/wx/core/ext.rb

@@ -28,18 +28,37 @@ module Wx
       end
     end
 
+    class Value
+      def initialize(code, block)
+        @code = code
+        @block = block
+      end
+
+      def value
+        @block ? @block.call : Kernel.eval(@code || 'nil')
+      end
+
+      def to_s
+        @code || ''
+      end
+    end
+
     def delayed_constants
       @delayed_constants ||= ::Hash.new
     end
 
     public
 
-    def add_delayed_constant(mod, sym, &block)
-      delayed_constants[Key.new(mod,sym)] = block
+    def add_delayed_constant(mod, sym, code='', &block)
+      delayed_constants[Key.new(mod,sym)] = Value.new(code, block)
+    end
+
+    def delayed_constants_for(mod)
+      delayed_constants.select { |k,v| k.mod == mod }
     end
 
     def load_delayed_constants
-      delayed_constants.each_pair { |key, blk| key.mod.const_set(key.sym, blk.call) }
+      delayed_constants.each_pair { |key, val| key.mod.const_set(key.sym, val.value) }
       delayed_constants.clear # cleanup
     end
 

data/lib/wx/core/secret_store.rb

@@ -0,0 +1,38 @@
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+
+module Wx
+
+  class SecretStore
+
+    # Wipes the secret data.
+    def self.wipe(secret)
+      if ::String === secret
+        secret.bytesize.times { |i| secret.setbyte(i, 0) }
+      end
+    end
+
+  end
+
+  class SecretValue
+
+    # Redefine the initialize method to auto-convert UTF-16/-32 strings to UTF-8 if possible.
+    wx_init = self.instance_method(:initialize)
+    define_method(:initialize) do | *args |
+      if args.size == 1 && ::String === args.first
+        unless args.first.encoding == ::Encoding::UTF_8 || args.first.encoding == ::Encoding::ASCII_8BIT
+          # convert in place unless frozen
+          if !args.first.frozen?
+            args.first.encode!(::Encoding::UTF_8) rescue nil
+          else # create converted copy
+            (args = [args.first.encode(::Encoding::UTF_8)]) rescue nil
+          end
+        end
+      end
+      wx_init.bind(self).call(*args)
+    end
+
+  end
+
+end

data/lib/wx/doc/extra/02_lifecycles.md

@@ -155,12 +155,12 @@ There are however quite a lot of wrapped native objects in wxRuby for which *obj
 object tracking has been disabled for their classes. This means these kind of classes/object should **not** be derived from
 (if even possible and/or useful) to add functionality/information or their identity used as key to link other information.<br>
 These classes include:
-* classes considered POD types like Wx::Size, Wx::Point, Wx::RealPoint, Wx::Rect, Wx::GBSpan, Wx::GBPosition, Wx::BusyInfoFlags,
+- classes considered POD types like Wx::Size, Wx::Point, Wx::RealPoint, Wx::Rect, Wx::GBSpan, Wx::GBPosition, Wx::BusyInfoFlags,
 Wx::AboutDialogInfo
-* final non-instantiatable classes like the Wx::DC (Device Context) class family, Wx::GraphicsContext, Wx::WindowsDisabler,
+- final non-instantiatable classes like the Wx::DC (Device Context) class family, Wx::GraphicsContext, Wx::WindowsDisabler,
 Wx::EventBlocker, Wx::BusyInfo
-* classes with native singleton objects like Wx::Clipboard
-* the reference counted GDI objects like Wx::Pen, Wx::Brush, Wx::Colour, Wx::Cursor, Wx::Bitmap, Wx::Icon and similar 
+- classes with native singleton objects like Wx::Clipboard
+- the reference counted GDI objects like Wx::Pen, Wx::Brush, Wx::Colour, Wx::Cursor, Wx::Bitmap, Wx::Icon and similar 
 reference counted objects like Wx::Font
 
 The reference documentation will note untracked object classes.

data/lib/wx/doc/extra/14_config.md

@@ -87,7 +87,7 @@ Another difference is that {Wx::Config} will not automatically create missing gr
 happen when writing configuration values.
 
 A last difference is that the default support is by default backed up by persistent storage (windows registry or file) and
-the wxRuby enhanced support only provides in-memory storage (`Hash` instance) by default. +
+the wxRuby enhanced support only provides in-memory storage (`Hash` instance) by default.<br>
 Persisting configuration data from {Wx::Config} will require coding customized storage and retrieval operations (which is
 trivial using standard YAML or JSON support).  
 

data/lib/wx/doc/secret_store.rb

@@ -0,0 +1,55 @@
+# :stopdoc:
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+# :startdoc:
+
+
+module Wx
+
+  class SecretStore
+
+    # Wipes the secret data.
+    # @param [String] secret string containing secret data
+    # @return [void]
+    def self.wipe(secret); end
+
+  end
+
+  class SecretValue
+
+    # @overload initialize()
+    #   Creates an empty secret value (not the same as an empty password).
+    #   @return [Wx::SecretValue]
+    # @overload initialize(secret)
+    #   Creates a secret value from the given string.
+    #   The secret argument may contain NUL bytes.
+    #   Any UTF-8 encoded (or encodable; wxRuby will attempt re-encoding as UTF-8 for any string not encoded UTF-8 or ASCII-8BIT) string will be stored as UTF-8 encoded string.
+    #   In these cases use {#get_as_string} if needing to compare the original string to a restored string.
+    #   Otherwise the string will be stored as ASCII-8BIT encoded string.
+    #   In these cases use {#get_data} if needing to compare the original string to a restored string.
+    #   See {#==} for comparing secret values opaquely.
+    #   @param secret [String]
+    #   @return [Wx::SecretValue]
+    # @overload initialize(other)
+    #   Creates a copy of an existing secret.
+    #   @param other [Wx::SecretValue]
+    #   @return [Wx::SecretValue]
+    def initialize(*args) end
+
+    # Returns a copy of the secret data as an ASCII-8BIT encoded String.
+    # Be aware this could be binary data and may contain embedded NUL characters.
+    # For more security {Wx::SecretStore.wipe} should be used to wipe the secret data after use.
+    # @return [String] secret data
+    def get_data; end
+
+    # Returns a copy of the secret data as an UTF-8 encoded String.
+    # Make sure to use this method only if sure that the secret originally stored was indeed
+    # UTF-8 data as otherwise the returned string will not match the stored data.
+    # For more security {Wx::SecretStore.wipe} should be used to wipe the secret data after use.
+    # @return [String] secret data
+    def get_as_string; end
+
+  end
+
+end

data/lib/wx/version.rb

@@ -3,5 +3,5 @@
 # This software is released under the MIT license.
 
 module Wx
-  WXRUBY_VERSION    = '0.9.5'
+  WXRUBY_VERSION    = '0.9.8'
 end

data/lib/wx/wxruby/base.rb

@@ -20,17 +20,20 @@ module WxRuby
       def commands
         @commands ||= ::Hash.new do |hash, key|
           STDERR.puts "Unknown command #{key} specified."
-          exit(1)
+          exit(127)
         end
       end
       private :commands
 
+      def setup_done?
+        File.exist?(File.join(WxRuby::ROOT, 'ext', 'wxruby.setup.done'))
+      end
+
       def options
         @options ||= {
           :verbose => false
         }
       end
-      private :options
 
       def register(cmdid, cmdhandler)
         commands[cmdid.to_s] = case
@@ -59,7 +62,7 @@ module WxRuby
       def parse_args(args)
         opts = OptionParser.new
         opts.banner = "Usage: wxruby [global options] COMMAND [arguments]\n\n" +
-            "    COMMAND\t\t\tSpecifies wxruby command to execute."
+            "    COMMAND\t\t\t\tSpecifies wxruby command to execute."
         opts.separator ''
         opts.on('-v', '--verbose',
                 'Show verbose output') { |v| ::WxRuby::Commands.options[:verbose] = true }
@@ -70,8 +73,7 @@ module WxRuby
           describe_all
           exit(0)
         end
-        opts.raise_unknown = false
-        opts.parse!(args)
+        opts.order!(args) rescue ($stderr.puts $!.message; exit(127))
       end
     end
   end
@@ -79,9 +81,7 @@ module WxRuby
   def self.run(argv = ARGV)
     # parse global options (upto first command)
     argv = WxRuby::Commands.parse_args(argv)
-    while !argv.empty?
-      WxRuby::Commands.run(argv.shift, argv)
-    end
+    WxRuby::Commands.run(argv.shift, argv) unless argv.empty?
   end
 end
 

data/lib/wx/wxruby/cmd/check.rb

@@ -0,0 +1,182 @@
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+
+# wxruby check command handler
+#--------------------------------------------------------------------
+
+require 'fileutils'
+require 'plat4m'
+
+module WxRuby
+  module Commands
+
+    class Check
+
+      LOAD_ERRORS = {
+        linux: /cannot\s+open\s+shared\s+object/i,
+        darwin: /library\s+not\s+loaded/i,
+        windows: /specified\s+module\s+could\s+not\s+be\s+found/i
+      }
+
+      DESC = 'Run wxRuby3 runtime readiness check.'
+
+      def self.description
+        "    check -h|[options]\t\t\t#{DESC}"
+      end
+
+      def self.options
+        Commands.options['check'] ||= { verbose: Commands.options[:verbose] }
+      end
+
+      def self.parse_args(args)
+        opts = OptionParser.new
+        opts.banner = "#{DESC}\n\nUsage: wxruby check -h|--help OR wxruby check [options]\n\n" +
+                      "Returns:\n"+
+                      "   0   if wxRuby3 is ready to run\n"+
+                      "   1   if wxRuby3 does not seem to be built yet\n"+
+                      "   2   if wxRuby3 has problems loading extension libraries\n"+
+                      "   3   if an unexpected Ruby error occurred\n\n"+
+                      "Unless '-q|--quiet' has been specified a description of the possible problem cause will\n"+
+                      "be shown on failure.\n\n"
+        opts.separator ''
+        opts.on('-q', '--quiet',
+                "Do not show problem analysis messages on failures.") do |v|
+          Check.options[:quiet] = true
+          Check.options[:verbose] = false
+        end
+        opts.on('-v', '--verbose',
+                'Show verbose output') do |v|
+          Check.options[:verbose] = true
+          Check.options[:quiet] = false
+        end
+        opts.on('-h', '--help',
+                'Show this message.') do |v|
+          puts opts
+          puts
+          exit(0)
+        end
+        opts.parse!(args) rescue ($stderr.puts $!.message; exit(127))
+      end
+
+      def self.show_error(msg)
+        $stderr.puts(msg) unless options[:quiet]
+      end
+
+      def self.show_log(msg)
+        $stdout.puts(msg) if options[:verbose]
+      end
+
+      def self.run(argv)
+        return description if argv == :describe
+
+        parse_args(argv)
+
+        show_log('Checking build (or binary package installation) completion...')
+        # check if the binary setup (packages or built) has been completed successfully
+        unless Commands.setup_done?
+          $stderr.puts <<~__INFO_TXT
+
+            wxRuby3 requires the post-install setup cmd to be run to build and finish installing
+            the required runtime binaries. Execute the command like:
+
+            $ wxruby setup
+
+            To see the available options for the command execute:
+
+            $ wxruby setup -h
+ 
+          __INFO_TXT
+          exit(1)
+        end
+
+        # check runtime
+        show_log('Attempting to load wxRuby3 libraries...')
+        sysinfo = Plat4m.current
+        begin
+          require 'wx'
+        rescue LoadError => ex
+          if ex.message =~ LOAD_ERRORS[sysinfo.os.id]
+            # error loading shared libraries
+            show_log("Captured LoadError: #{ex.message}")
+            # check if wxWidgets libs can be located
+            show_log('Checking wxWidgets availability...')
+            wx_found = if Dir[File.join(WxRuby::ROOT, 'ext', "*.#{RbConfig::CONFIG['SOEXT']}")].empty?
+                         # no embedded wxWidgets -> if system installed than 'wx-config' should be in the path
+                         if system("wx-config --version>#{sysinfo.dev_null} 2>&1")
+                           true # system installed
+                         else
+                           # no system installed wxWidgets
+                           # check the system dependent load paths if any wxWidgets libs can be found
+                           case sysinfo.os.id
+                           when :linux
+                             (ENV['LD_LIBRARY_PATH']||'').split(':').any? { |p| !Dir[File.join(p, 'libwx_base*.so')].empty? }
+                           when :darwin
+                             (ENV['DYLD_LIBRARY_PATH']||'').split(':').any? { |p| !Dir[File.join(p, 'libwx_base*.dylib')].empty? }
+                           when :windows
+                             (ENV['PATH']||'').split(';').any? { |p| !Dir[File.join(p, 'wxbase*.dll')].empty? }
+                           else
+                             true # do not know how to search so assume wxWidgets found
+                           end
+                         end
+                       else
+                         true # embedded wxWidgets
+                       end
+            if wx_found
+              show_log('wxWidgets found')
+              show_error <<~__INFO_TXT
+
+                The runtime environment of this system seems to be missing some required libraries for
+                executing wxRuby3 apps.
+                Please be aware wxRuby3 requires a properly configured GUI based system to function.
+                See the documentation for more information on the required runtime environment.   
+     
+                __INFO_TXT
+            else
+              show_log('NO wxWidgets found')
+              show_error <<~__INFO_TXT
+
+                It seems wxRuby3 is not able to load any of the required wxWidgets libraries it was built
+                for.
+                Please make sure these (shared) libraries are available in the appropriate search path
+                for this system. 
+     
+                __INFO_TXT
+            end
+          else
+            show_error <<~__INFO_TXT
+
+              There is an unexpected problem loading the wxRuby3 extension libraries.
+              Please check the problem report below for a probable cause analysis. If you have reason
+              to suspect a bug to be the cause of this problem please file an issue at Github and attach 
+              the problem report. 
+
+              #{ex.message}
+              #{ex.backtrace.join("\n")}
+   
+              __INFO_TXT
+          end
+          exit(2)
+        rescue Exception => ex
+          show_log("Captured Exception: #{ex.message}")
+          show_error <<~__INFO_TXT
+
+            There is an unexpected problem loading the wxRuby3 libraries.
+            Please check the problem report below for a probable cause analysis. If you have reason
+            to suspect a bug to be the cause of this problem please file an issue at Github and attach 
+            the problem report. 
+
+            #{ex.message}
+            #{ex.backtrace.join("\n")}
+ 
+            __INFO_TXT
+          exit(3)
+        end
+      end
+
+    end
+
+    self.register('check', Check)
+
+  end
+end

data/lib/wx/wxruby/cmd/sampler.rb

@@ -10,44 +10,54 @@ require 'fileutils'
 module WxRuby
   module Commands
     class Sampler
-      OPTIONS = {
-        save_path: nil
-      }
+
+      DESC = 'Run wxRuby3 Sampler application (or copy samples).'
 
       def self.description
-        "    sampler [help]|[copy DEST]\tRun wxRuby3 Sampler application (or copy samples)."
+        "    sampler -h|[options]\t\t#{DESC}"
+      end
+
+      def self.options
+        Commands.options['sampler'] ||= { verbose: Commands.options[:verbose] }
+      end
+
+      def self.parse_args(args)
+        opts = OptionParser.new
+        opts.banner = "#{DESC}\n\nUsage: wxruby sampler -h|--help OR wxruby sampler [options]\n\n" +
+          "Runs the sampler application if no options specified.\n\n"
+        opts.separator ''
+        opts.on('--copy=DEST',
+                'Copies the included wxRuby sample folders under the directory indicated by DEST (MUST exist)')  {|v| Sampler.options[:copy] << v }
+        opts.on('-h', '--help',
+                'Show this message.') do |v|
+          puts opts
+          puts
+          exit(0)
+        end
+        opts.parse!(args) rescue ($stderr.puts $!.message; exit(127))
       end
 
       def self.run(argv)
-        if argv == :describe
-          description
-        else
-          if argv.empty?
-            exec(RUBY, File.join(WxRuby::ROOT, 'samples', 'sampler.rb'))
-          else
-            arg = argv.shift
-            if arg == 'help'
-              puts 'Usage: wxruby [global options] sampler [help]|[copy DEST]'
-              puts
-              puts '    Starts the sampler application if called without arguments.'
-              puts '    Otherwise shows this help for argument "help" or copies the included wxRuby'
-              puts '    sample folders under the directory indicated by DEST for argument "copy DEST".'
-              puts '    The directory indicated by DEST *must* already exist.'
-              puts
-            elsif arg == 'copy'
-              unless File.directory?(dest = argv.shift)
-                STDERR.puts "ERROR: Invalid destination folder #{dest}"
-                exit(1)
-              end
-              Dir[File.join(WxRuby::ROOT, 'samples', '*')].each do |fp|
-                FileUtils.cp_r(fp, dest, verbose: true)
-              end
-            end
+        return description if argv == :describe
+
+        parse_args(argv)
+
+        if options[:copy]
+          unless File.directory?(dest = options[:copy])
+            $stderr.puts "ERROR: Invalid destination folder #{dest}"
+            exit(1)
           end
+          Dir[File.join(WxRuby::ROOT, 'samples', '*')].each do |fp|
+            FileUtils.cp_r(fp, dest, verbose: true)
+          end
+        else
+          exec(RUBY, File.join(WxRuby::ROOT, 'samples', 'sampler.rb'))
         end
       end
     end
 
-    self.register('sampler', Sampler)
+    if self.setup_done?
+      self.register('sampler', Sampler)
+    end
   end
 end