wxruby3 0.9.7 → 0.9.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d5a9a4c753ce46aa02eddc50cd51d51928a7e00b25172d2eae30ad4a2a87547
-  data.tar.gz: 36e5955935cf757e5aca26cf2df1b0ef3821e1c9a353508149ef4e0d95e2caa3
+  metadata.gz: 5c45580184f8f7ee466f9ec158bcb9f28702f6674ab42abc735f7235cc3482bd
+  data.tar.gz: f22f78e25c135b2583bfd60a7712c1084b8be8b3550d695e1acf65eac19b2223
 SHA512:
-  metadata.gz: fbf51eea1ad3411d80f3f01c8d08f601b04096e3cd36dae6eb29d073157b87dd430cda87a73b89430d5fddc64a8b43ba29e3e45f28a201b180b0bd87ead3ccad
-  data.tar.gz: ddd00e990557c587970ff0326eed3e61376ef74de243e7a1795cb7238d3aba06a2da15e4caa8b5438c6c34931ded3b486dbaea955e79cbf91b803013d732b4b4
+  metadata.gz: 401ff95651f766ac947eba8a1a58a77be718182a473549f49eeee5b361a019051da88f529aec58bfe88dd46b5104dbae64a96eba5fa14d6a3e446fcece35c6f0
+  data.tar.gz: fe9f01627e61ddc1ff5c18936dbf71f1cf09fd7d6ce372b6cc25062051a3807b3e6a0fe59179753ce0a1f9577f856eefca58c0564d0860a6e607d14bba428606

data/INSTALL.md

@@ -8,25 +8,26 @@
 
 The wxRuby3 gem provides a **worry-free** installation for all supported platforms.
 
-The default gem installation commands 
+The default gem installation command
+
 ```shell
 gem install wxruby3
 ``` 
 
-for Windows and 
+and the setup command  
 
 ```shell
-gem install wxruby3 && wxruby setup
+wxruby setup
 ```
-for Linux and MacOSX (see Note below) and Windows (if installing for Ruby releases older than the latest stable release) 
-should always result in a successfully installed wxRuby3 version.<br>
-Just follow the (very few and in some cases none) prompts at the start of the setup procedure and sit back and relax.
+
+for installations without prebuilt binary packages should always result in a successfully installed wxRuby3 version.
 
 > **NOTE**<br>
 > Currently installing the wxRuby3 gem for the system supplied Ruby on MacOSX systems does not work.<br>
 > The user is therefor required to install a Ruby interpreter using either [MacPorts](https://www.macports.org/) (both 
 > privileged and user installations are supported) or [Homebrew](https://brew.sh/) or Ruby installers/version managers 
-> like [ruby-install](https://github.com/postmodern/ruby-install) or [RVM](https://rvm.io) (only user installations supported) .
+> like [ruby-install](https://github.com/postmodern/ruby-install) or [RVM](https://rvm.io) (only user installations 
+> supported) .
 
 [Below](INSTALL.md#installing-software-requirements) more details regarding the software requirements for wxRuby3, the 
 setup procedure and various options to tweak and customize the installation (including platform specific details for 
@@ -36,16 +37,65 @@ Linux, Windows and MacOSX) are described.
 
 Installing the wxRuby3 gem will also install the bundled `wxruby` CLI binary.
 
-For source gem installations the CLI will initially only provide the *setup* command.
+For source gem installations the CLI will initially only provide the `check` and `setup` commands.
 
-For binary gem installations and successfully set up source gem installations the *setup* command is replaced by other 
+For finalized installations (either from binary packages or source builds) the *setup* command is replaced by other 
 utility commands providing the ability to run the bundled regression tests and access (run or copy) the bundled examples.<br>
 Run the following command to see the available options at any time:
 
 ```shell
-wxruby --help
+wxruby -h
 ```
 
+## Binary packages
+
+The wxRuby3 gem installation process will by default attempt to match the current platform to any standard available
+binary packages and if found install the matched package.
+
+Binary packages are archives (custom format) containing prebuilt (extension) library artifacts for a single specific
+platform. Any such platform is identified by:
+
+- CPU architecture (x86_64, ARM64, etc.)
+- Operating system type (linux, darwin, windows, etc.)
+- OS distribution and release number (except for windows)
+- Ruby ABI version (i.e. {major}.{minor})
+
+The standard available binary packages provide both the wxRuby3 extension libraries as well as the embedded wxWidgets 
+libraries the extension libraries were built for.<br>
+This is however not mandatory. User created binary packages can be built for separately installed (either distribution 
+or user provided) wxWidgets libraries.
+
+### Standard packages
+
+The standard release artifacts at [Github](https://github.com/mcorino/wxRuby3/releases) provide a selection of binary
+packages for all supported OS platforms which are automatically built and uploaded for every release.<br>
+The following tables lists the packages provided by the current wxRuby3 release process:
+
+| OS      | Distributions                 | Architectures           | Rubies                                             |
+|---------|-------------------------------|-------------------------|----------------------------------------------------|
+| Linux   | OpenSuSE Leap (latest stable) | x86_64 <b>and</b> ARM64 | Distro provided Ruby <b>and</b> Latest stable Ruby |  
+| Linux   | Fedora (latest stable)        | x86_64 <b>and</b> ARM64 | Distro provided Ruby <b>and</b> Latest stable Ruby |  
+| Linux   | Debian (latest stable)        | x86_64 <b>and</b> ARM64 | Distro provided Ruby <b>and</b> Latest stable Ruby |  
+| Linux   | Ubuntu (latest stable)        | x86_64 <b>and</b> ARM64 | Distro provided Ruby <b>and</b> Latest stable Ruby |
+| Windows | NA                            | x86_64                  | Latest stable Ruby                                 |
+| OSX     | MacOSX 12                     | x86_64 <b>and</b> ARM64 | Latest stable Ruby                                 |
+| OSX     | MacOSX 13                     | x86_64 <b>and</b> ARM64 | Latest stable Ruby                                 |
+| OSX     | MacOSX 14                     | ARM64                   | Latest stable Ruby                                 |
+
+### User created packages
+
+Users can create their own wxRuby3 binary packages by building from source ([see here](#building-from-source)) and after
+successfully having built the wxWidgets extension libraries execute the `rake binpkg` command.<br>
+This creates two files in the `pkg` folder with names like<br>
+`wxruby3_{distribution}_ruby{abi version}_v{wxruby version}_{os}_{arch}.pkg`<br>
+and<br>
+`wxruby3_{distribution}_ruby{abi version}_v{wxruby version}_{os}_{arch}.sha`<br>
+where the `.pkg` file is the actual binary archive and the `.sha` file is the associated SHA256 digest signature of the 
+archive contents.
+
+Both files are required for installation and should be located at the same path (either local path or http(s) url).<br>
+[See here](#the-package-option) for information on how to use user created binary packages with the wxRuby3 gem installation process.
+
 ## Software requirements for wxRuby3
 
 The software requirements for setting up a wxRuby3 runtime environment are:
@@ -90,63 +140,129 @@ wxRuby3 can be built and installed for 3 different types of wxWidgets installati
    In this case the libraries and development files are most likely not found in standard locations and the wxRuby3 
    installation procedure will require specific options to have these locations provided. 
 3. An 'embedded' installation of wxWidgets setup by the wxRuby3 installation procedure.<br>
-   This is the default when the installation procedure does not detect a (compatible!) system installation or if an 
-   option has been provided explicitly specifying to install an embedded wxWidgets version.
+   This is the default when using a standard binary package or when installing from source and the setup procedure does 
+   not detect a (compatible!) system installation or if an option has been provided explicitly specifying to install an 
+   embedded wxWidgets version.
 
 Please note that in case of option **2** the user is responsible to make sure the wxWidgets shared libraries can be
 found by the system's dynamic loader at runtime.
 
-As described with option **3** a wxWidgets system installation must be compatible (>= version 3.2) to be selected. In case 
-the installed version does not meet this requirement it is ignored as if not installed.
+As described with option **3** a wxWidgets system installation must be compatible (>= version 3.2) to be selected for 
+source installation. In case the installed version does not meet this requirement it is ignored as if not installed.
 
 For more information on how to install wxWidgets see the [Installing software requirements](INSTALL.md#installing-software-requirements) section below.
 
 ## wxRuby3 gem installation details 
 
-The wxRuby3 project provides gems on [RubyGems](https://rubygems.org) which can be installed with the
+The wxRuby3 project provides a gem on [RubyGems](https://rubygems.org) which can be installed with the
 standard `gem install` command line this:
 
 ```shell
 gem install wxruby3
  ```
 
-On Linux and MacOSX systems this will install the source based gem which will require a follow-up command to build the native wxruby3 extension
-for the platform on which wxRuby3 is being installed.<br>
-On Windows systems a prebuilt binary gem is available for the latest stable release(s) of [RubyInstaller](https://rubyinstaller.org) 
-installed rubies that will be installed by default if installing for that platform (including an embedded, latest 
-stable version, wxWidgets installation).<br>
-Alternatively the source gem can be installed on Windows by installing with an explicit platform specification like this:
+Alternatively the gem can be downloaded from the [Github release assets](https://github.com/mcorino/wxRuby3/releases) and
+stored locally. This local gem can than be installed like this:
 
 ```shell
-gem install wxruby3 --platform=ruby
+gem install /path/to/local/wxruby3.gem
 ```
 
-> The result of installing the gem on a Linux platform should be something like this:
+This default installation command will allow the wxRuby3 installation process to scan available standard binary packages
+([see here](#standard-packages)) for a match to the platform being installed on and install any matched package or revert
+to a source install if none matched.<br>
+This command will therefor succeed if:
+- a matching binary package could be successfully downloaded and installed;
+- the installation reverted to source install.
+
+This command only fails when:
+- a matching digest signature for the downloaded binary package could not be downloaded;
+- the digest signature did not match the downloaded package contents.
+
+> The result of successfully installing the gem on a Linux platform should be something like this:
 > ```
 > $ gem install wxruby3 
+> Building native extensions. This could take a while...
 > 
-> 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.
 > 
-> Run 'wxruby setup -h' to see information on the available commandline options.
->
-> Successfully installed wxruby3-0.9.5
-> Parsing documentation for wxruby3-0.9.5
-> Installing ri documentation for wxruby3-0.9.5
-> Done installing documentation for wxruby3 after 10 seconds
+> 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:
+> 
+> $ wxruby sampler
+> 
+> Have fun using wxRuby3.
+> 
+> Run 'wxruby -h' to see information on the available commands.
+> 
+> Successfully installed wxruby3-0.9.8
+> Parsing documentation for wxruby3-0.9.8
+> Installing ri documentation for wxruby3-0.9.8
+> Done installing documentation for wxruby3 after 2 seconds
 > 1 gem installed
 > ```
 
-As said, on Linux and MacOSX systems (also on Windows when installing the source gem) an additional command is required 
-to build the actual wxRuby3 extension libraries for the platform which is a wxRuby3 CLI command installed by the gem:
+### Gem installation options
+
+Two options are available to control the wxRuby3 gem installation process.
+
+#### The `prebuilt` option
+
+The `prebuilt=none|only` option can be used to either prevent binary package matching and installation (`prebuilt=none`)
+or make binary package installation mandatory (`prebuilt=only`).
+
+The following command therefor forces a wxRuby3 source installation and will never fail: 
+
+```shell
+gem install wxruby3 -- prebuilt=none
+```
+
+And the following command will force binary package installation and fails if no matching package could be installed:
+
+```shell
+gem install wxruby3 -- prebuilt=only
+```
+
+#### The `package` option
+
+The `package=URL` option can be used to explicitly specify a binary package to install. This option implies `prebuilt=only`.
+No package matching will be performed so mismatched binary packages will cause wxRuby3 to fail after installation.<br>
+The `URL` can be specified as:
+- an <b>absolute</b> local path like `/path/to/binary/package.pkg`
+- an absolute `file://` URI like `file:///path/to/binary/package.pkg`
+- an `http://` or `https://` URL
+
+In all cases the associated `.sha` file <b>must</b> be located at the same path as the package file itself. If not the
+installation will fail as well as when the signature does not match the digest of the package contents.
+
+### Gem source setup
+
+As said a gem-based source installation requires an additional command is to build the actual wxRuby3 extension libraries 
+for the platform installing on which is a wxRuby3 CLI command installed by the gem:
 
 ```shell
 wxruby setup
 ```
 
 The wxRuby3 CLI `wxruby` is installed by all wxRuby3 gems. In case of the source gem initially the CLI will provide only 
-a single command `wxruby setup` to finish wxRuby3 extension (build and) installation.
+the commands `wxruby setup` (to finish wxRuby3 extension installation) and `wxruby check`.
 
 For most (user) installations the default setup command as shown above will suffice nicely. In this case the setup 
 (or installation) procedure will analyze the system to see if it meets the software requirements described above and if not
@@ -184,7 +300,7 @@ The initial message shown (between lines starting with '---' ) is indicative of
 on options passed to the setup command.<br>
 Building the wxRuby3 native extensions and generating reference documentation will always happen.
 
-### Disable prompting for automatic install 
+#### Disable prompting for automatic install 
 
 To prevent having the setup procedure asking consent the setup procedure can be started with the `--autoinstall` option 
 like this:
@@ -195,7 +311,7 @@ wxruby setup --autoinstall
 
 Note that on Linux that may still present a prompt in case the `sudo` command requires a password.
 
-### Prevent automatic installation of software requirements
+#### Prevent automatic installation of software requirements
 
 To prevent the setup procedure from considering to automatically install (with or without prompting) any missing software
 requirements the setup procedure can be started with the `--no-autoinstall` option like this: 
@@ -207,7 +323,7 @@ wxruby setup --no-autoinstall
 The setup procedure will still analyze the system for available software requirements and if it finds any missing it
 will end the procedure and show a message of what it found missing.
 
-### Force embedded wxWidgets installation
+#### Force embedded wxWidgets installation
 
 To prevent the setup procedure of using any system installed wxWidgets version the setup procedure can be started with 
 the `--with-wxwin` option like this:
@@ -218,7 +334,7 @@ wxruby setup --with-wxwin
 
 This will force the setup procedure to build and install an embedded wxWidgets version for wxRuby3.
 
-### Setup with user installed wxWidgets
+#### Setup with user installed wxWidgets
 
 In case of a (custom) user installation of wxWidgets the `--wxwin` (and optionally `--wxxml`) option(s) can be used to
 start the setup procedure to build for this installation like this:
@@ -241,7 +357,7 @@ wxruby setup --wxwin=/my/custom/wxWidgets --wxxml=/my/alternate/wxWidgets/xml
 > responsible for making sure the wxRuby3 extension library can find the wxWidgets libraries at runtime (normally this
 > requires updating the standard shared library search path for the platform).
 
-### Setup with customized tool paths
+#### Setup with customized tool paths
 
 If for whatever reason the required development tools `doxygen`, `swig` and/or `git` have been installed in a location
 not in the standard executable search path the full path to these tools can be passed on the setup procedure using the
@@ -251,7 +367,7 @@ not in the standard executable search path the full path to these tools can be p
 wxruby setup --doxygen=/my/path/to/doxygen
 ```
 
-### Redirect log to customized path
+#### Redirect log to customized path
 
 The setup procedure will log full build results to a file setup.log at the location where the gem contents is stored.
 If the setup fails the error message will display the log file location and by default if the setup succeeds the log 
@@ -364,7 +480,7 @@ Checkout the wxRuby3 sources from [GitHub](https://github.com/mcorino/wxRuby3) o
 Requirements are the same as for installing the source gem. Gem dependencies are listed in the Gemfile in the root
 of the wxRuby3 tree and should be installed by executing `bundle install`.<br>
 To be able to generate HTML documentation the optional `:documentation` group should be included.<br>
-To be able to run the Rake memory check task the option `:develop` group should be included.
+To be able to run the Rake memory check task the optional `:develop` group should be included.
 
 The wxRuby3 project provides a Rake based build system. Call `rake help` to get an overview of the available commands.
 As mentioned there the `rake configure` command is required as the very first command. Call `rake configure[--help]` to
@@ -376,4 +492,7 @@ commands are executed using parallel task execution by default.
 
 When the build has finished without errors the regression tests can be run by calling `rake test`.
 
+After successfully building the wxRuby3 extension libraries (and possibly embedded wxWidgets libraries) a binary package
+can be created by call `rake binpkg`.
+
 For more details concerning the wxRuby3 development strategy and build options see [here](TODO). 

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; all major AMD-64 distributions: Ubuntu, Debian, Fedora, OpenSuSE and ArchLinux)<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 (MacPorts, Homebrew, ruby-install, RVM) | 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,43 +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 release 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).
 
 The wxRuby3 gem provides a **worry-free** installation procedure for all supported platforms.  
 
-Installing the binary gem version on Windows (which is the default when installing for the latest stable Ruby release for 
-that platform) requires no additional installation steps and/or additional software to be installed except for a supported 
-version of the Ruby interpreter. So for this platform the following command is all it takes to get up and running: 
+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: 
 
 ```shell
 gem install wxruby3
 ```
 
-For the platforms requiring a source based installation (Linux and MacOSX as well as Windows for older Ruby releases 
-or when explicitly selecting source based install) an additional (simple) setup step is required to finish installation.
-For these platforms the full installation sequence would be:
+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
+wxruby setup
 ```
 
-The second part of this command sequence 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.
+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.
+> 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/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.7'
+  WXRUBY_VERSION    = '0.9.8'
 end