wxruby3 0.9.7 → 1.0.0

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

@@ -34,7 +34,7 @@ module WxRuby
           puts
           exit(0)
         end
-        opts.parse!(args)
+        opts.parse!(args) rescue ($stderr.puts $!.message; exit(127))
       end
 
       def self.run(argv)

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

@@ -14,7 +14,7 @@ module WxRuby
       DESC = 'Run wxRuby3 post-install setup.'
 
       def self.description
-        "    setup -h|[options]\t\t#{DESC}"
+        "    setup -h|[options]\t\t\t#{DESC}"
       end
 
       def self.options
@@ -26,11 +26,16 @@ module WxRuby
         opts.banner = "#{DESC}\n\nUsage: wxruby setup -h|--help OR wxruby setup [options]\n\n"
         opts.separator ''
         opts.on('--wxwin=path',
-                "the installation root for the wxWidgets libraries and headers if not using the system default")  {|v| Setup.options['wxwin'] = File.expand_path(v)}
+                "the installation root for the wxWidgets libraries and headers if not using the system default",
+                "(use '@system' to force using system default only)") do |v|
+          Setup.options['wxwin'] = (v.downcase == '@system') ? v : File.expand_path(v)
+        end
         opts.on('--wxxml=path',
                 "the path to the doxygen generated wxWidgets XML interface specs if not using bootstrap")  {|v| Setup.options['wxxml'] = File.expand_path(v)}
         opts.on('--with-wxwin',
                 "build a local copy of wxWidgets for use with wxRuby [false]")  {|v| Setup.options['with-wxwin'] = true}
+        opts.on('--with-wxhead',
+                "build with the head (master) version of wxWidgets [false]", "(implies '--with-wxwin')")  {|v| Setup.options['with-wxhead'] = true}
         opts.on('--swig=path',
                 "the path to swig executable [swig]")  {|v| Setup.options['swig'] = v}
         opts.on('--doxygen=path',
@@ -47,7 +52,7 @@ module WxRuby
           puts
           exit(0)
         end
-        opts.parse!(args)
+        opts.parse!(args) rescue ($stderr.puts $!.message; exit(127))
       end
 
       def self.run(argv)
@@ -59,6 +64,7 @@ module WxRuby
         cfg_args << "--wxwin=#{Setup.options['wxwin']}" if Setup.options['wxwin']
         cfg_args << "--wxxml=#{Setup.options['wxxml']}" if Setup.options['wxxml']
         cfg_args << '--with-wxwin' if Setup.options['with-wxwin']
+        cfg_args << '--with-wxhead' if Setup.options['with-wxhead']
         cfg_args << "--swig=#{Setup.options['swig']}" if Setup.options['swig']
         cfg_args << "--doxygen=#{Setup.options['doxygen']}" if Setup.options['doxygen']
         cfg_args << "--git=#{Setup.options['git']}" if Setup.options['git']

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

@@ -45,7 +45,7 @@ module WxRuby
           puts
           exit(0)
         end
-        opts.parse!(args)
+        opts.parse!(args) rescue ($stderr.puts $!.message; exit(127))
       end
 
       def self.run(argv)

data/rakelib/configure.rb

@@ -57,13 +57,33 @@ module WXRuby3
         opts.on('--sodir=path',
                 "the directory for ruby extensions [#{get_config('sodir')}]")  {|v| CONFIG['sodir'] = v}
         opts.on('--wxwin=path',
-                "the installation root for the wxWidgets libraries and headers if not using the system default")  {|v| CONFIG['wxwin'] = File.expand_path(v)}
+                "the installation root for the wxWidgets libraries and headers if not using the system default",
+                "(use '@system' to force using system default only)")  { |v|
+          if v.downcase == '@system'
+            CONFIG[WXW_SYS_KEY] = true
+            CONFIG['wxwin'] = nil
+            CONFIG['with-wxwin'] = false
+            CONFIG['with-wxhead'] = false
+          else
+            CONFIG['wxwin'] = File.expand_path(v)
+            CONFIG[WXW_SYS_KEY] = false
+          end
+        }
         opts.on('--wxxml=path',
                 "the path to the doxygen generated wxWidgets XML interface specs if not using bootstrap")  {|v| CONFIG['wxxml'] = File.expand_path(v)}
         opts.on('--wxwininstdir=path',
-                "the directory where the wxWidgets dlls are to be installed for wxRuby [#{instance.get_config('wxwininstdir')}]") {|v| CONFIG['wxwininstdir'] = v}
+                "the directory where the wxWidgets dlls are installed (do not change if not absolutely needed) [#{instance.get_config('wxwininstdir')}]") {|v| CONFIG['wxwininstdir'] = v}
         opts.on('--with-wxwin',
-                "build a local copy of wxWidgets for use with wxRuby [false]")  {|v| CONFIG['with-wxwin'] = true}
+                "build a local copy of wxWidgets for use with wxRuby [false]")  { |v|
+          CONFIG['with-wxwin'] = true
+          CONFIG[WXW_SYS_KEY] = false
+        }
+        opts.on('--with-wxhead',
+                "build with the head (master) version of wxWidgets; implies '--with-wxwin'")  { |v|
+          CONFIG['with-wxhead'] = true
+          CONFIG['with-wxwin'] = true
+          CONFIG[WXW_SYS_KEY] = false
+        }
         opts.on('--with-debug',
                 "build with debugger support [#{instance.get_config('with-debug')}]")  {|v| CONFIG['with-debug'] = true}
         opts.on('--swig=path',
@@ -84,69 +104,64 @@ module WXRuby3
     def self.check
       instance.init # re-initialize
 
-      if Dir[File.join('ext', 'wxruby_*.so')].empty? # Don't check for wxWidgets installation when executed for binary gem install
+      # should we try to use a system or user defined wxWidgets installation?
+      if !get_config('with-wxwin')
 
-        if !get_config('with-wxwin')
-          # check if a user defined wxWidgets location is specified or we're using a system standard install
-          if get_cfg_string('wxwin').empty?
-            # assume system standard install; will be checked below
-            set_config('wxwininstdir', get_cfg_string('libdir')) if get_cfg_string('wxwininstdir').empty?
-          elsif get_cfg_string('wxwininstdir').empty?
-            if instance.windows?
-              set_config('wxwininstdir', File.join(get_cfg_string('wxwin'), 'bin'))
-            else
-              set_config('wxwininstdir', File.join(get_cfg_string('wxwin'), 'lib'))
-            end
-          end
-        elsif !get_cfg_string('wxwin').empty?
-          if get_cfg_string('wxwininstdir').empty?
-            if instance.windows?
-              set_config('wxwininstdir', File.join(get_cfg_string('wxwin'), 'bin'))
-            else
-              set_config('wxwininstdir', File.join(get_cfg_string('wxwin'), 'lib'))
-            end
+        # check if a user defined wxWidgets location is specified or should be using a system standard install
+        if get_cfg_string('wxwin').empty?
+          # assume/force system standard install; will be checked below
+          set_config('wxwininstdir', get_cfg_string('libdir')) if get_cfg_string('wxwininstdir').empty?
+        elsif get_cfg_string('wxwininstdir').empty? # if not explicitly specified derive from 'wxwin'
+          if instance.windows?
+            set_config('wxwininstdir', File.join(get_cfg_string('wxwin'), 'bin'))
+          else
+            set_config('wxwininstdir', File.join(get_cfg_string('wxwin'), 'lib'))
           end
-        else
-          set_config('wxwininstdir', get_cfg_string('sodir')) if get_cfg_string('wxwininstdir').empty?
         end
 
-        if !get_cfg_string('wxwin').empty? || !get_config('with-wxwin')
-          # check wxWidgets availability through 'wx-config' command
-          if instance.check_wx_config
-            if instance.wx_config("--version") < '3.2.0'
-              if get_cfg_string('wxwin').empty? && get_cfg_string('wxxml').empty?
-                # no custom wxWidgets build specified so switch to assuming we should include building wxWidgets ourselves
-                set_config('with-wxwin', true)
-              else
-                # if someone wants to customize they HAVE to do it right
-                STDERR.puts "ERROR: Incompatible wxWidgets version. wxRuby requires a wxWidgets >= 3.2.0 release."
-                exit(1)
-              end
-            end
-          else
-            if get_cfg_string('wxwin').empty? && get_cfg_string('wxxml').empty?
-              # no custom wxWidgets build specified so switch to assuming we should include building wxWidgets ourselves
+      # or should we use an embedded (automatically built) wxWidgets installation
+      else
+
+        set_config('wxwininstdir', instance.ext_dir)
+
+      end
+
+      if !get_cfg_string('wxwin').empty? || !get_config('with-wxwin')
+        # check wxWidgets availability through 'wx-config' command
+        if instance.check_wx_config
+          if instance.wx_config("--version") < '3.2.0'
+            if get_cfg_string('wxwin').empty? && get_cfg_string('wxxml').empty? && !get_config(WXW_SYS_KEY)
+              # no custom (or forced system) wxWidgets build specified so switch to assuming we should include building wxWidgets ourselves
               set_config('with-wxwin', true)
             else
               # if someone wants to customize they HAVE to do it right
-              STDERR.puts "ERROR: Cannot find wxWidgets. wxRuby requires a wxWidgets >= 3.2.0 release."
+              STDERR.puts "ERROR: Incompatible wxWidgets version. wxRuby requires a wxWidgets >= 3.2.0 release."
               exit(1)
             end
           end
-        # else we're are assumed to build wxWidgets ourselves so cannot test anything yet
-        end
-
-        if get_cfg_string('wxxml').empty? && !get_cfg_string('wxwin').empty?
-          # in case of a custom wxWidgets build and no explicit xml path check if the custom build holds this
-          xml_path = File.join(get_cfg_string('wxwin'), 'docs', 'doxygen', 'out', 'xml')
-          # if not there see if the standard setup 'wxw_root/<install dir>' was used
-          xml_path = File.join(get_cfg_string('wxwin'), '..', 'docs', 'doxygen', 'out', 'xml') unless File.directory?(xml_path)
-          if File.directory?(xml_path) && !Dir.glob(File.join(xml_path, '*.xml')).empty?
-            set_config('wxxml', xml_path)
+        else
+          if get_cfg_string('wxwin').empty? && get_cfg_string('wxxml').empty? && !get_config(WXW_SYS_KEY)
+            # no custom (or forced system) wxWidgets build specified so switch to assuming we should include building wxWidgets ourselves
+            set_config('with-wxwin', true)
+          else
+            # if someone wants to customize they HAVE to do it right
+            STDERR.puts "ERROR: Cannot find wxWidgets. wxRuby requires a wxWidgets >= 3.2.0 release."
+            exit(1)
           end
         end
+      # else we're assumed to build wxWidgets ourselves so cannot test anything yet
+      end
 
+      if get_cfg_string('wxxml').empty? && !get_cfg_string('wxwin').empty?
+        # in case of a custom wxWidgets build and no explicit xml path check if the custom build holds this
+        xml_path = File.join(get_cfg_string('wxwin'), 'docs', 'doxygen', 'out', 'xml')
+        # if not there see if the standard setup 'wxw_root/<install dir>' was used
+        xml_path = File.join(get_cfg_string('wxwin'), '..', 'docs', 'doxygen', 'out', 'xml') unless File.directory?(xml_path)
+        if File.directory?(xml_path) && !Dir.glob(File.join(xml_path, '*.xml')).empty?
+          set_config('wxxml', xml_path)
+        end
       end
+
     end
 
   end

data/rakelib/gem.rake

@@ -12,14 +12,10 @@ namespace :wxruby do
 
   namespace :gem do
 
-    task :srcgem => ['bin:build', WXRuby3::Gem.gem_file('wxruby3', WXRuby3::WXRUBY_VERSION)]
+    task :srcgem => ['bin:build', WXRuby3::Gem.gem_file]
 
-    if WXRuby3.is_bootstrapped?
-      task :bingem => ['bin:build', File.join(WXRuby3.config.rb_docgen_path, 'window.rb'), WXRuby3::Gem.gem_file('wxruby3', WXRuby3::WXRUBY_VERSION, :bin)]
-    end
-
-    # this task only exists for installed source gems (where package tasks have been removed)
-    unless File.file?(File.join(__dir__, 'package.rake'))
+    # this task only exists for installed (source) gems (where run tasks have been removed)
+    unless File.file?(File.join(__dir__, 'run.rake'))
 
       task :setup => 'config:bootstrap' do |_t, args|
         begin
@@ -51,7 +47,7 @@ namespace :wxruby do
       
           $ ./wxruby test
       
-          The wxRuby3 sample selector can be run by executing:
+          The wxRuby3 sample explorer can be run by executing:
       
           $ ./wxruby sampler
       
@@ -65,13 +61,14 @@ namespace :wxruby do
 end
 
 # source gem file
-file WXRuby3::Gem.gem_file('wxruby3', WXRuby3::WXRUBY_VERSION) => WXRuby3::Gem.manifest do
-  gemspec = WXRuby3::Gem.define_spec('wxruby3', WXRuby3::WXRUBY_VERSION) do |gem|
+file WXRuby3::Gem.gem_file => WXRuby3::Gem.manifest do
+  gemspec = WXRuby3::Gem.define_spec do |gem|
     gem.summary = %Q{wxWidgets extension for Ruby}
     gem.description = %Q{wxRuby3 is a Ruby library providing an extension for the wxWidgets C++ UI framework}
     gem.email = 'mcorino@m2c-software.nl'
     gem.homepage = "https://github.com/mcorino/wxRuby3"
     gem.authors = ['Martin Corino']
+    gem.extensions = ['ext/mkrf_conf_ext.rb']
     gem.files = WXRuby3::Gem.manifest
     gem.require_paths = %w{lib}
     gem.bindir = 'bin'
@@ -82,6 +79,7 @@ file WXRuby3::Gem.gem_file('wxruby3', WXRuby3::WXRUBY_VERSION) => WXRuby3::Gem.m
     gem.add_dependency 'rake'
     gem.add_dependency 'minitest', '~> 5.15'
     gem.add_dependency 'test-unit', '~> 3.5'
+    gem.add_dependency 'plat4m', '~> 1.0'
     gem.rdoc_options <<
       '--exclude=\\.dll' <<
       '--exclude=\\.so' <<
@@ -90,17 +88,40 @@ file WXRuby3::Gem.gem_file('wxruby3', WXRuby3::WXRUBY_VERSION) => WXRuby3::Gem.m
       "'--exclude=lib/wx/(aui|core|grid|html|pg|prt|rbn|rtc|stc|wxruby)/.*'"
     gem.metadata = {
       "bug_tracker_uri"   => "https://github.com/mcorino/wxRuby3/issues",
+      "homepage_uri"      => "https://github.com/mcorino/wxRuby3/wiki",
       "source_code_uri"   => "https://github.com/mcorino/wxRuby3",
       "documentation_uri" => "https://mcorino.github.io/wxRuby3",
-      "homepage_uri"      => "https://github.com/mcorino/wxRuby3",
+      "github_repo"       => "https://github.com/mcorino/wxRuby3"
     }
     gem.post_install_message = <<~__MSG
 
-      The wxRuby3 Gem has been successfully installed.
-      Before being able to use wxRuby3 you need to run the post-install setup process
-      by executing the command 'wxruby setup'.
+      The wxRuby3 Gem has been successfully installed including the 'wxruby' utility.
+
+      In case no suitable binary release package was available for your platform you  
+      will need to run the post-install setup process by executing:
+
+      $ wxruby setup
+
+      To check whether wxRuby3 is ready to run or not you can at any time execute the 
+      following command:
+
+      $ wxruby check
+
+      Run 'wxruby check -h' for more information.
+
+      When the wxRuby3 setup has been fully completed you can start using wxRuby3.
+ 
+      You can run the regression tests to verify the installation by executing:
+
+      $ wxruby test
+
+      The wxRuby3 sample explorer can be run by executing:
 
-      Run 'wxruby setup -h' to see information on the available commandline options.
+      $ wxruby sampler
+
+      Have fun using wxRuby3.
+
+      Run 'wxruby -h' to see information on the available commands.
 
       __MSG
   end
@@ -110,60 +131,70 @@ end
 desc 'Build wxRuby 3 gem'
 task :gem => 'wxruby:gem:srcgem'
 
-if WXRuby3.is_bootstrapped?
-
-  # binary gem file
-  file WXRuby3::Gem.gem_file('wxruby3', WXRuby3::WXRUBY_VERSION, :bin) => WXRuby3::Gem.manifest(:bin) + ['ext/mkrf_conf_bingem.rb'] do
-    WXRuby3::Install.install_wxwin_shlibs
-    begin
-      # create gemspec
-      gemspec = WXRuby3::Gem.define_spec('wxruby3', WXRuby3::WXRUBY_VERSION, :bin) do |gem|
-        gem.summary = %Q{wxWidgets extension for Ruby}
-        gem.description = %Q{wxRuby3 is a Ruby library providing an extension for the wxWidgets C++ UI framework}
-        gem.email = 'mcorino@m2c-software.nl'
-        gem.homepage = "https://github.com/mcorino/wxRuby3"
-        gem.authors = ['Martin Corino']
-        gem.files = WXRuby3::Gem.manifest(:bin)
-        gem.require_paths = %w{lib}
-        gem.require_paths << 'ext' if WXRuby3.config.get_config('with-wxwin')
-        gem.bindir = 'bin'
-        gem.executables = WXRuby3::Bin.binaries
-        gem.extensions = ['ext/mkrf_conf_bingem.rb']
-        gem.required_ruby_version = ">= #{WXRuby3::Config.rb_ver_major}.#{WXRuby3::Config.rb_ver_minor}",
-                                    "< #{WXRuby3::Config.rb_ver_major}.#{WXRuby3::Config.rb_ver_minor+1}"
-        gem.licenses = ['MIT']
-        gem.add_dependency 'rake'
-        gem.add_dependency 'minitest', '~> 5.15'
-        gem.add_dependency 'test-unit', '~> 3.5'
-        gem.rdoc_options << '--exclude=\\.dll' << '--exclude=\\.so'
-        gem.metadata = {
-          "bug_tracker_uri"   => "https://github.com/mcorino/wxRuby3/issues",
-          "source_code_uri"   => "https://github.com/mcorino/wxRuby3",
-          "documentation_uri" => "https://mcorino.github.io/wxRuby3",
-          "homepage_uri"      => "https://github.com/mcorino/wxRuby3",
-        }
-        gem.post_install_message = <<~__MSG
-    
-          wxRuby3 has been successfully installed including the 'wxruby' utility.
-    
-          You can run the regression tests to verify the installation by executing:
-    
-          $ ./wxruby test
-    
-          The wxRuby3 sample selector can be run by executing:
-    
-          $ ./wxruby sampler
-    
-          Have fun using wxRuby3.
-          __MSG
+# these tasks do not exist for installed (source) gems (where run tasks have been removed)
+if File.file?(File.join(__dir__, 'run.rake'))
+
+  if WXRuby3.is_bootstrapped?
+
+    namespace :wxruby do
+
+      namespace :gem do
+        task :binpkg => ['wxruby:build', 'wxruby:doc', 'bin:build', WXRuby3::Gem.bin_pkg_file]
       end
-      WXRuby3::Gem.build_gem(gemspec)
-    ensure
-      WXRuby3::Install.remove_wxwin_shlibs
+
     end
+
+    # binary package file
+    file WXRuby3::Gem.bin_pkg_file => WXRuby3::Gem.bin_pkg_manifest do |t|
+      WXRuby3::Install.install_wxwin_shlibs
+      begin
+        # create bin package
+        WXRuby3::Gem.build_bin_pkg
+      ensure
+        # cleanup
+        WXRuby3::Install.remove_wxwin_shlibs
+      end
+    end
+
+    desc 'Build wxRuby 3 binary release package'
+    task :binpkg => 'wxruby:gem:binpkg'
+
   end
 
-  desc 'Build wxRuby 3 binary gem'
-  task :bingem => 'wxruby:gem:bingem'
+else # in case of installed source gem the following tasks exist
+
+  namespace :wxruby do
+
+    namespace :gem do
+      kwargs = {}
+      no_prebuilt = false
+      task :install do |_, args|
+        argv = args.extras
+        until argv.empty?
+          switch = argv.shift
+          case switch
+          when '--prebuilt'
+            kwargs[:prebuilt_only] = true
+          when '--no-prebuilt'
+            no_prebuilt = true unless kwargs[:package]
+          when '--package'
+            fail "Missing value for '--package' argument for wxruby:gem:install." if argv.empty?
+            kwargs[:package] = argv.shift
+            no_prebuilt = false
+          else
+            fail "Invalid argument #{switch} for wxruby:gem:install."
+          end
+        end
+        unless no_prebuilt # do not even try to find&install a binary package
+          if WXRuby3::Gem.install_gem(**kwargs)
+            # binaries have been installed -> finish install
+            Rake::Task['wxruby:post:binpkg'].invoke
+          end
+        end
+      end
+
+    end
+
+  end
 
 end