wxruby3 0.9.7 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d5a9a4c753ce46aa02eddc50cd51d51928a7e00b25172d2eae30ad4a2a87547
-  data.tar.gz: 36e5955935cf757e5aca26cf2df1b0ef3821e1c9a353508149ef4e0d95e2caa3
+  metadata.gz: 22f63fb730a7c17f84eac51d892cad2f35ef33211d88fafde508fe7c222712e6
+  data.tar.gz: 2cf9e0b4026e8c00b24873e77af5f4d5676e5af3181e6459104b5c6fef0675d1
 SHA512:
-  metadata.gz: fbf51eea1ad3411d80f3f01c8d08f601b04096e3cd36dae6eb29d073157b87dd430cda87a73b89430d5fddc64a8b43ba29e3e45f28a201b180b0bd87ead3ccad
-  data.tar.gz: ddd00e990557c587970ff0326eed3e61376ef74de243e7a1795cb7238d3aba06a2da15e4caa8b5438c6c34931ded3b486dbaea955e79cbf91b803013d732b4b4
+  metadata.gz: 48cce7a08e4f4bd15380178cab3ab38b53af6942d5054af617806d5b01bea0aabc26887ec26fc07a6bb6c2d9802ec512d59396a2361c88a12635ebf80b066d91
+  data.tar.gz: eba7856af27dcfe0e4eb50662bae9bb00af12f29258e0eb4b2d446c3351446651926e2e5c0eec017038fef2545671e8ac47faea0f75c1bb3efd54c751585ae08

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,22 @@ 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
+#### Force embedded wxWidgets head installation
+
+To force the setup procedure to build and install an embedded wxWidgets head (master) version the setup procedure can 
+be started with the `--with-wxhead` option like this:
+
+```shell
+wxruby setup --with-wxhead
+```
+
+> **NOTE**<br>
+> Although wxRuby3 endeavors to keep up to date with the wxWidgets master branch your mileage may vary depending on
+> the development state of the wxWidgets master branch. You can check the latest results of the wxRuby3 CI master build 
+> workflows of the [wxRuby3 Github Actions](https://github.com/mcorino/wxRuby3/actions) to get a feel of the current 
+> integration state. 
+
+#### 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 +372,14 @@ 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
+> **NOTE 2**<br>
+> Please be aware that when building a user installation of wxWidgets on Windows this has to be done using the exact
+> same compiler suite as used for building Ruby (and it's standard native extensions) itself.<br>
+> Currently only RubyInstaller versions are supported which use the MingW64 compiler.
+> Do **NOT** install a separate MSYS2/MingW64 release but rather use a RubyInstaller version with integrated DevKit 
+> installation (which includes MSYS2 and the right MingW64 compiler suite).
+
+#### 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 +389,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 +502,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 +514,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 calling `rake binpkg`.
+
 For more details concerning the wxRuby3 development strategy and build options see [here](TODO). 

data/README.md

@@ -41,7 +41,8 @@ end
 
 Anyone who is familiar with wxWidgets should feel right at home since the API may be Ruby-fied, it is still easily 
 recognizable (but being Ruby-fied allowing for elegant and compact coding). And for those that do not have previous 
-experience, do not fear, wxRuby3 comes with detailed [documentation](https://mcorino.github.io/wxRuby3/file.00_starting.html) and lots of examples and tests.    
+experience, do not fear, wxRuby3 comes with an extensive [User Guide](https://github.com/mcorino/wxRuby3/wiki/User-Guide-%3A-Introduction) 
+and detailed [reference documentation](https://mcorino.github.io/wxRuby3) and lots of examples and tests.    
 
 ```ruby
 require 'wx'
@@ -90,17 +91,19 @@ README and license files for details.
 See [here](CREDITS.md) for more details on and acknowledgement of the developers 
 of these products.
 
-## FAQ
+## (Some of the) Most Frequently Asked Questions
+
+(see the extended [FAQ](https://github.com/mcorino/wxRuby3/wiki/Frequently-Asked-Questions) in the [Wiki](https://github.com/mcorino/wxRuby3/wiki) for more information)
  
 ### What platforms and operating systems are supported in wxRuby3?
 
 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,53 +112,59 @@ 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.
 
 When asking a question, if something is not working as you expect,
 please provide a *minimal*, *runnable* sample of code that demonstrates
-the problem, and say what you expected to happen, and what actually
+the problem, and describe clearly what you expected to happen and what actually
 happened. Please also provide basic details of your platform, Ruby,
 wxRuby and wxWidgets version, and make a reasonable effort to find answers 
-in the archive and documentation before posting. People are mostly happy
+in the archive, wiki and/or documentation before posting. People are mostly happy
 to help, but it's too much to expect them to guess what you're trying to
 do, or try and debug 1,000 lines of your application.
 Very important also; do not use offensive language and be **polite**.
@@ -171,13 +180,17 @@ some use a more modern coding style than others. Use the bundled `wxruby`
 CLI to access the samples (see the section **Bundled CLI** in 
 the [INSTALL](INSTALL.md) document for more details).
 
+An extensive [User Guide](https://github.com/mcorino/wxRuby3/wiki/User-Guide-%3A-Introduction) 
+is available at the [wxRuby3 Wiki](https://github.com/mcorino/wxRuby3/wiki) providing detailed
+information about how to build desktop applications with wxRuby3. 
+
 Complete (more or less) wxRuby API documentation should be part of any
 complete wxRuby3 build. This tends to focus on providing a reference
 of all available modules, classes and methods and how to use specific 
 classes and methods, rather than on how to construct an application 
 overall.
 This documentation (for the latest release) is also available online
-[here](https://mcorino.github.io/wxRuby3/file.00_starting.html).
+[here](https://mcorino.github.io/wxRuby3).
 
 One of the advantages of wxRuby3 is the much larger ecosystem of
 wxWidgets and wxPython resources out there. There is a book for
@@ -193,18 +206,6 @@ example, if you wanted answers about the "Grid" class, try searching for
 "wxGrid" as this will turn up results relating to wxWidgets and wxPython
 which may be relevant.
 
-### What wxWidgets features are supported by wxRuby3?
-
-wxRuby supports almost all of the wxWidgets 3.2+ GUI API, providing over
-600 classes in total. wxWidgets classes that provide general and/or non-GUI 
-programming support features, such as strings, networking, threading, database
-access and such are not and will never be ported, as it's assumed that 
-in all these cases it's preferable to use pure Ruby features.
-
-If you know of a feature in wxWidgets that you would like to see
-supported in wxRuby3 you are free to ask but do not **EXPECT** unconditional 
-agreement or immediate response. 
-
 ### How does wxRuby3 relate to the wxRuby 2.0 (and even older 0.6.0) release?
 
 wxRuby 0.6.0 was the last in a series of releases developed using a
@@ -225,12 +226,3 @@ maintainable solution.
 
 Please double-check the instructions above and in the [INSTALL](INSTALL.md) document and search issue archives. If 
 this doesn't help, please post your question using GitHub Issues.
-
-### Is there another, more declarative way, for writing wxRuby3 desktop GUI applications?
-
-Yes. [Glimmer DSL for WX](https://github.com/AndyObtiva/glimmer-dsl-wx) enables software engineers to build GUI 
-using wxruby3 following the Ruby way with the least amount of code possible. That is by offering a minimalistic 
-declarative high-level DSL that maps visually to the way software engineers think about the GUI hierarchy in addition 
-to adopting Rails' strategy of Convention over Configuration via smart defaults and automation of wxruby3 low-level 
-details. You can check out the [Glimmer DSL for WX README "Coming From wxruby3" section](https://github.com/AndyObtiva/glimmer-dsl-wx#coming-from-wxruby3) for more information on 
-how to translate wxruby3 apps to [Glimmer DSL for WX](https://github.com/AndyObtiva/glimmer-dsl-wx) syntax.

data/ext/mkrf_conf_ext.rb

@@ -0,0 +1,72 @@
+# 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|head)$/
+    OPTIONS[:prebuilt] = $1.to_sym
+  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?
+  case OPTIONS[:prebuilt]
+  when :only
+    task_args << "'--prebuilt'"
+  when :none
+    task_args << "'--no-prebuilt'"
+  end
+end
+if OPTIONS[:package]
+  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.join(', ')})
+  end
+end
+EOF__
+end

data/lib/wx/core/app.rb

@@ -14,6 +14,22 @@ require_relative './ext'
 # Controller class which creates and manages all windows.
 class Wx::App
 
+  if Wx::PLATFORM == 'WXOSX'
+    class << self
+      # provide aliases for macosx specials
+      alias :mac_about_menu_itemid= :set_mac_about_menu_itemid
+      alias :mac_about_menu_itemid :get_mac_about_menu_itemid
+      alias :mac_preferences_menu_itemid= :set_mac_preferences_menu_itemid
+      alias :mac_preferences_menu_itemid :get_mac_preferences_menu_itemid
+      alias :mac_exit_menu_itemid= :set_mac_exit_menu_itemid
+      alias :mac_exit_menu_itemid :get_mac_exit_menu_itemid
+      alias :mac_help_menu_title= :set_mac_help_menu_title
+      alias :mac_help_menu_title :get_mac_help_menu_title
+      alias :mac_window_menu_title= :set_mac_window_menu_title
+      alias :mac_window_menu_title :get_mac_window_menu_title
+    end
+  end
+
   # convenience method to retrieve global Wx::App instance
   def self.the_app
     if Wx::const_defined?(:THE_APP) and Wx::THE_APP.is_running