wxruby3 0.9.5-x64-mingw-ucrt → 0.9.7-x64-mingw-ucrt

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0ad2e04d5e9c1abdb9af5996fb90f9840998e61791ef6e70dfd38451dc6cc96
-  data.tar.gz: 650f43b258547d2bf337f3dad0562f92991fee005b99c64347eeab9ae2f8e125
+  metadata.gz: de6a6f3d68dc67a60da8abf0b8f3964a8b5ae07cbb814c6d37fe39424ae761a2
+  data.tar.gz: 939d2798c7bd84c5bd498704698db4aa068c1d673d44c73752be6f9d0b5b411e
 SHA512:
-  metadata.gz: 944eec6b06fd0503e651e5a02760a1ff8e50f2c1f61ea3e0e706d61a7c62e8ee045cda7a6f03e5d1a99eaec2284ba5722e3f70a6fdcd068b0c7ebd6d680de7dc
-  data.tar.gz: 9f1588496325b7253cd5a110ca3309b92f59b6d7537e0f53a8c8ce002a1b0d5907896a205b44da75b02035a8c1a7ef7b688cea91b02eb53101e849c6215801ed
+  metadata.gz: 430e06a96542e2b29b6fe5a3a6c4b6a6263fe22347a53a62192c93902e1889501ec7a9b18520a999e392566f6130c3f167bddb9ac1c53cbf745ac86f440cae43
+  data.tar.gz: ccb5ccd3f573e3fa5b7e0bdefc460bc476a3c0a233bc2d389a3c38610563b06f43425c0e72155d9fe5019ac7f0d6e2288dc6d3c7724ce7157c388230fdb9dcf8

data/.wxconfig

@@ -1,17 +1,18 @@
 {
-  "libruby": "C:/hostedtoolcache/windows/Ruby/3.2.2/x64/lib/ruby",
-  "librubyver": "C:/hostedtoolcache/windows/Ruby/3.2.2/x64/lib/ruby/3.2.0",
-  "librubyverarch": "C:/hostedtoolcache/windows/Ruby/3.2.2/x64/lib/ruby/3.2.0/x64-mingw-ucrt",
-  "siteruby": "C:/hostedtoolcache/windows/Ruby/3.2.2/x64/lib/ruby/site_ruby",
-  "siterubyver": "C:/hostedtoolcache/windows/Ruby/3.2.2/x64/lib/ruby/site_ruby/3.2.0",
-  "siterubyverarch": "C:/hostedtoolcache/windows/Ruby/3.2.2/x64/lib/ruby/site_ruby/3.2.0/x64-ucrt",
+  "libruby": "C:/hostedtoolcache/windows/Ruby/3.2.3/x64/lib/ruby",
+  "librubyver": "C:/hostedtoolcache/windows/Ruby/3.2.3/x64/lib/ruby/3.2.0",
+  "librubyverarch": "C:/hostedtoolcache/windows/Ruby/3.2.3/x64/lib/ruby/3.2.0/x64-mingw-ucrt",
+  "siteruby": "C:/hostedtoolcache/windows/Ruby/3.2.3/x64/lib/ruby/site_ruby",
+  "siterubyver": "C:/hostedtoolcache/windows/Ruby/3.2.3/x64/lib/ruby/site_ruby/3.2.0",
+  "siterubyverarch": "C:/hostedtoolcache/windows/Ruby/3.2.3/x64/lib/ruby/site_ruby/3.2.0/x64-ucrt",
   "rbdir": "$siterubyver",
   "sodir": "$siterubyverarch",
   "wxwin": "",
   "wxxml": "",
-  "wxwininstdir": "C:/hostedtoolcache/windows/Ruby/3.2.2/x64/lib/ruby/site_ruby/3.2.0/x64-ucrt",
+  "wxwininstdir": "C:/hostedtoolcache/windows/Ruby/3.2.3/x64/lib/ruby/site_ruby/3.2.0/x64-ucrt",
   "with-wxwin": true,
   "with-debug": false,
   "swig": "swig",
-  "doxygen": "doxygen"
+  "doxygen": "doxygen",
+  "git": "git"
 }

data/INSTALL.md

@@ -4,28 +4,104 @@
 
 # Installation of wxRuby3
 
-Below are installation instructions for Linux, Windows, and Mac (both AMD64 and ARM64).
+## Default installation
 
-## Minimal requirements for installing wxRuby3
+The wxRuby3 gem provides a **worry-free** installation for all supported platforms.
 
-The minimal requirements for installing any source based setup (gem, source package or Github clone) of wxRuby3 are:
+The default gem installation commands 
+```shell
+gem install wxruby3
+``` 
+
+for Windows and 
+
+```shell
+gem install wxruby3 && 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.
+
+> **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) .
+
+[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 
+Linux, Windows and MacOSX) are described.
+
+## Bundled CLI
+
+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 binary gem installations and successfully set up source gem installations 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
+```
+
+## Software requirements for wxRuby3
+
+The software requirements for setting up a wxRuby3 runtime environment are:
+
+| Sofware                                       | Notes                                                                                                                                                                                                                                                                                                                        |
+|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Ruby                                          | A supported version of the Ruby interpreter needs to be installed. This is an absolute requirement for any installation as one cannot install gems without Ruby and building from source requires Ruby to drive the build process.                                                                                           |
+| C++ compiler<br>(incl. dev tools like `make`) | Required for a source based installation to build wxWidgets (optionally) and the wxRuby extension libraries.<br/>On linux a recent version of the GNU C++ compiler (with c++-14 support) is required.<br>On Windows the RubyInstaller MSYS2-Devkit would be required.<br>On MacOS XCode with commandline tools would be required. |
+| Git version control toolkit                   | Required for a source based installation in to (possibly) clone a copy of the wxWidgets Github repository or to clone the Github repository of wxRuby3 itself for a fully source based installation.                                                                                                                         |
+| Doxygen (>= 1.9.1)                            | Required for building the wxRuby3 extension libraries for a source based installation. [**1**]                                                                                                                                                                                                                               |
+| SWIG >= 3.0.12                                | Required for building the wxRuby3 extension libraries for a source based installation. [**2**]                                                                                                                                                                                                                               |
+| Patchelf (Linux) or install_name_tool (OSX)   | Required for setting up embedded wxWidgets libraries. [**3**]                                                                                                                                                                                                                                                                |
+| wxWidgets (>= 3.2)                            | Runtime libraries required for any wxRuby3 installation (either from embedded wxWidgets installation or a system or user installation; see below).                                                                                                                                                                           |
+
+Except for Ruby itself all other software requirements can be handled by the **worry-free**, fully automated installation procedure of wxRuby3.
+
+But of course any of these requirements can also be fulfilled explicitly with self controlled steps **before** starting the
+wxRuby3 installation procedure. See the platform specific sections of [Installing software requirements](INSTALL.md#installing-software-requirements) for details on 
+how to go about that. 
+
+[**1**] The wxRuby3 build process needs doxygen to generated XML files containing wxWidgets interface specs which are used to 
+generate interface definitions for SWIG
+
+[**2**] The wxRuby3 build process uses SWIG to generate C++ source code for the wrapper interfaces from
+which the native extensions are compiled. Both SWIG version 3 and version 4 are supported.
 
-| Sofware                                       | Notes                                                                                                                                                                                                                                                                        |
-|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Ruby                                          | A supported version of the Ruby interpreter needs to be installed.                                                                                                                                                                                                           |
-| C++ compiler<br>(incl. dev tools like `make`) | On linux a recent version of the GNU C++ compiler (with c++-14 support) needs to be installed<br>On Windows the RubyInstaller MSYS2-Devkit needs to be installed<br>On MacOS XCode with commandline tools needs to be installed via <code>sudo xcode-select --install</code> |
-| Git version control toolkit                   |                                                                                                                                                                                                                                                                              |
-| SWIG >= 3.0.12                                | On MacOS install Homebrew (https://brew.sh) and than <code>brew install swig</code>                                                                                                                                                                                          |
-| Doxygen (>= 1.9.1)                            | On MacOS install Homebrew (https://brew.sh) and than <code>brew install doxygen@</code>                                                                                                                                                                                      |
-| wxWidgets (>= 3.2)                            | See the <b>wxWidgets installation</b> section below.                                                                                                                                                                                                                         |
+[**3**] The wxRuby3 build process uses these tools to adjust the shared library load paths ('rpath' setting) in case of embedded wxWidgets libraries.
 
-The wxRuby3 build process requires `git` to clone a copy of the wxWidgets Github repository to extract the interface 
-specifications from.<br>
-The wxRuby3 build process needs doxygen to generated XML files containing wxWidgets interface specs which are used to 
-generate SWIG interface definitions from which SWIG to generates C++ source code for the wrapper interfaces from
-which the native extension is compiled.
+### wxWidgets installation variants
 
-## Installation of a wxRuby3 Gem
+wxRuby3 can be built and installed for 3 different types of wxWidgets installations:
+
+1. A system installation of wxWidgets libraries and development files.<br>
+   This actually only has real meaning on Linux where this corresponds with installing distribution provided packages. 
+   On MacOSX and Windows this only means that libraries are installed (as a user addon since no standard distribution 
+   packages exist for these platforms but possibly using the administrator account) such that they can be loaded using 
+   the default library load paths and the `wx-config` tool is executable from the default search path.<br>
+   This kind of installation is automatically detected and no special setup options are required for the wxRuby3 installation procedure.  
+2. A user installation of wxWidgets libraries and development files.<br>
+   This is the most likely scenario for a development setup of wxRuby3 where a special (possibly updated) release of 
+   wxWidgets is installed to build wxRuby3 for.<br>
+   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.
+
+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.
+
+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
 standard `gem install` command line this:
@@ -34,92 +110,253 @@ standard `gem install` command line this:
 gem install wxruby3
  ```
 
-On Linux systems this will install the source based gem which will automatically build the native wxruby3 extension
-for the platform on which wxRuby3 is being installed.
+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 explicit platform specification like this:
+Alternatively the source gem can be installed on Windows by installing with an explicit platform specification like this:
 
 ```shell
 gem install wxruby3 --platform=ruby
 ```
 
-When installing the source gem the minimal requirements listed above apply.
+> The result of installing the gem on a Linux platform should be something like this:
+> ```
+> $ gem install wxruby3 
+> 
+> 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'.
+> 
+> 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
+> 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:
 
-On MacOS, if wxWidgets was not available, you can pull in the latest wxWidgets and build it by adding the `WITH_WXWIN=1` option:
+```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.
+
+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
+collect information on what is missing and needs to be added to finish the wxRuby3 installation. In order this would check:
+
+- availability of the `doxygen` tool
+- availability of the `swig` tool
+- availability of the `git` tool
+- availability of a (compatible) system installation of wxWidgets
+- development tools and libraries required for an embedded wxWidgets installation (in case no system installation is used) 
+
+If any required software needs to be added the setup procedure will ask consent (showing what it intends to do) and, if given,
+install the missing software using appropriate tooling for the platform (on Linux standard distribution installers which 
+may require a 'sudo' password and on MacOSX using either [MacPorts](https://www.macports.org/) or [Homebrew](https://brew.sh/)).
+
+> Running the setup command will look something like this:
+> ```
+> $ wxruby setup
+> 
+> ---            
+> Now running wxRuby3 post-install setup.
+> This will (possibly) install required software, build the wxWidgets libraries,
+> build the native wxRuby3 extensions and generate the wxRuby3 reference documentation.
+> Please be patient as this may take quite a while depending on your system.
+> ---
+>
+> [ --- ATTENTION! --- ]
+> wxRuby3 requires some software packages to be installed before being able to continue building.
+> If you like these can be automatically installed next (if you are building the source gem the
+> software will be removed again after building finishes).
+> Do you want to have the required software installed now? [yN] :
+> ```
+
+The initial message shown (between lines starting with '---' ) is indicative of what is going to happen depending 
+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 
+
+To prevent having the setup procedure asking consent the setup procedure can be started with the `--autoinstall` option 
+like this:
 
 ```shell
-gem install wxruby3 -- WITH_WXWIN=1
+wxruby setup --autoinstall
 ```
 
-### wxWidgets installation
-
-Also a wxWidgets installation (version 3.2 or later) is required for which there are multiple options.
-
-1. System installed wxWidgets version (including development package)<br/>
-   <br/>
-   This is the default method used when installing the source gem without any options.<br>
-   The wxRuby build procedure will determine the availability and version of wxWidgets by locating and calling
-   the `wx-config` utility script. In case no (compatible) wxWidgets version is found installation ends with an error.<br>
-   Please note that even with this method a copy of the wxWidgets project will be checked out from GitHUb as the wxRuby3
-   build procedure requires access to the wxWidgets interface specification sources which are not normally part of any of 
-   the standard distribution packages.<br/> 
-   <br/>
-   On MacOS, you can install wxWidgets via [Homebrew](https://brew.sh/):
-   ```shell
-   brew install wxwidgets
-   ```
-   Afterwards, you can install the Ruby gem and it will detect wxWidgets in the system automatically:
-   ```shell
-   gem install wxruby3
-   ```   
-
-2. User installed wxWidgets version<br>
-   <br>
-   In case the system being installed on does not provide (a compatible) wxWidgets version or a specific (possibly updated)
-   wxWidgets version is required the source gem can be installed using a user installed version like this (where the 
-   `WXWIN` path should provide the location where the wxWidgets binaries are installed under `<wxwin path>/bin`):<br>
-   ```shell
-   gem install wxruby3 -- WXWIN=/path/to/wx/install 
-   ```
-
-3. Automatic installed, embedded, wxWidgets version<br>
-   <br>
-   This is the easiest method when the system being installed on does not provide (a compatible) wxWidgets version (and 
-   no specific user defined version is required) and can be used by installing the source gem like this (which will
-   cause automatic checkout and building of the latest stable wxWidgets release (>= 3.2) from GitHub:
-   ```shell
-   gem install wxruby3 -- WITH_WXWIN=1
-   ```
-
-In case of option **2** it is also possible to do the doxygen XML generation as part of the wxWidgets user installation
-and use that for the gem installation. In that case the user is required to generate the XML interface specs using the
-`regen` script found in the `docs/doxygen` folder of the wxWidgets installation after which the XML output folder can be 
-provided to the gem installation as follows:
+Note that on Linux that may still present a prompt in case the `sudo` command requires a password.
+
+### 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: 
 
 ```shell
-gem install wxruby3 -- WXWIN=/path/to/wx/install WXXML=/path/to/wx/doxygen/xml
+wxruby setup --no-autoinstall
 ```
 
-Please also not 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.
+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.
 
-> **NOTE:** Be patient when installing the source gem. Building wxRuby3 takes a while and when wxWidgets is included event more. 
+### Force embedded wxWidgets installation
 
-> **NOTE:** Be aware that for prerelease versions of the gem you should add the `--pre` argument to the `gem install` command. 
+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:
 
-### Bundled CLI
+```shell
+wxruby setup --with-wxwin
+```
 
-Installing the wxRuby3 gem will also install the bundled `wxruby` CLI binary.
+This will force the setup procedure to build and install an embedded wxWidgets version for wxRuby3.
 
-Currently this binary can be used to run the bundled regression tests and access (run or copy) the bundled examples.
-Run the following command to see the options:
+### 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:
 
 ```shell
-wxruby --help
+wxruby setup --wxwin=/my/custom/wxWidgets
+```
+
+If the wxWidgets installation also holds the doxygen generated XML interface specification files in the default location
+(`docs/doxygen/out/xml`) these will be used to build the wxRuby3 extensions. If not, the setup procedure will create these
+files itself (from a freshly cloned copy of the wxWidgets repository).<br>
+If the XML files have been created in a non-standard location that can be passed on to the setup procedure like this:
+
+```shell
+wxruby setup --wxwin=/my/custom/wxWidgets --wxxml=/my/alternate/wxWidgets/xml
+```
+
+> **NOTE**<br>
+> Please be aware that in case of building wxRuby3 for a user installation of wxWidgets the user is also 
+> 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
+
+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
+`--doxygen`, `--swig` and/or `--git` options like this:
+
+```shell
+wxruby setup --doxygen=/my/path/to/doxygen
+```
+
+### 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 
+file is deleted.<br>
+To redirect the log file to be stored at an alternate location an not be deleted in any case the `--log` option can be
+used like this:
+
+```shell
+wxruby setup --log=/my/log/folder
 ```
 
+In this case the log file would be created as `/my/log/folder/setup.log`.
+
+## Installing software requirements
+
+As described, instead of having the wxRuby3 setup procedure install the software requirements automatically these can 
+also be installed beforehand.
+
+The following sections give some information how to accomplish that for the various supported platforms.
+
+### Installing software requirements on Windows
+
+On Windows these software requirements are only needed when **not** installing the binary gem.
+
+#### Compiler
+
+Download and install the [RubyInstaller MSYS2-Devkit](https://rubyinstaller.org/downloads/) which includes both Ruby
+and a full set of development tools like GNU C++, make etc.
+
+#### Doxygen
+
+Download the Windows installer [here](https://doxygen.nl/download.html).
+
+#### SWIG
+
+Download the Windows archive [here](https://www.swig.org/download.html). 
+
+#### Git
+
+Any Windows compatible Git version will do like [this](https://gitforwindows.org/) one.
+
+#### wxWidgets
+
+See the information on the wxWidgets website [here](https://wxwidgets.org/downloads/). Download and install either
+a binary installation compatible with the MingW64 compiler version available from the RubyInstaller MSYS2-Devkit 
+installation (make sure to get this right or bad things will happen) or download a source package and build using the
+compiler tools from the RubyInstaller MSYS2-Devkit installation. See [here](https://docs.wxwidgets.org/3.2/overview_install.html) for information about
+building wxWidgets from source.
+
+### Installing software requirements on MacOSX
+
+#### Compiler
+
+Install the XCode commandline tools using the command <code>sudo xcode-select --install</code>.
+
+#### Doxygen
+
+Depending on how you installed Ruby on your MacOS system use [Homebrew](https://brew.sh) with the command <code>brew install doxygen</code> 
+or use [MacPorts](https://www.macports.org/) with the command <code>port install doxygen</code>.
+
+#### SWIG
+
+Depending on how you installed Ruby on your MacOS system use [Homebrew](https://brew.sh) with the command <code>brew install swig</code>
+or use [MacPorts](https://www.macports.org/) with the command <code>port install swig</code>.
+
+#### Git
+
+Is included in the XCode commandline tools. 
+
+#### wxWidgets
+
+Either install a compatible wxWidgets version (>= 3.2) with the package manager of choice (Homebrew or MacPorts) if available
+or download and build a source package from [here](https://wxwidgets.org/downloads/) (alternatively the wxWidgets Github 
+repository could be cloned). See [here](https://docs.wxwidgets.org/3.2/overview_install.html) for information about
+building wxWidgets from source.
+
+### Installing software requirements on Linux
+
+#### Compiler
+
+Install the GNU C++ compiler and common development tools like 'make' using the system provided package management.
+
+#### Patchelf
+
+Install the patchelf tool using the system provided package management.
+
+#### Doxygen
+
+Install the doxygen tool using the system provided package management.
+
+#### SWIG
+
+Install the swig tool using the system provided package management.
+
+#### Git
+
+Install the git tool using the system provided package management.
+
+#### wxWidgets
+
+Either install a compatible wxWidgets version (>= 3.2) with the system provided package management if available
+or download and build a source package from [here](https://wxwidgets.org/downloads/) (alternatively the wxWidgets Github
+repository could be cloned). See [here](https://docs.wxwidgets.org/3.2/overview_install.html) for information about
+building wxWidgets from source.
+
 ## Building from source
 
 Checkout the wxRuby3 sources from [GitHub](https://github.com/mcorino/wxRuby3) or download and unpack a release package.
@@ -132,7 +369,7 @@ To be able to run the Rake memory check task the option `:develop` group should
 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
 get a detailed overview of the options for this command.<br>
-As with the source gem 3 options exist for the wxWidgets installation which will have to be specified to `rake configure`.  
+As with the source gem 3 options exist for the wxWidgets installation for which details can be specified to `rake configure`.  
 
 When wxRuby3 has been configured the extensions can be build by calling the `rake build` command. The wxRuby3 build 
 commands are executed using parallel task execution by default.

data/README.md

@@ -96,11 +96,11 @@ of these products.
 
 Currently the following are fully supported:
 
-| Platform                                                                   | Ruby version(s)                             | wxWidgets version(s) |
-|----------------------------------------------------------------------------|---------------------------------------------|----------------------|
-| Windows 10 (tested)<br>(most likely also Windows 11)                       | Ruby >= 2.5<br>(RubyInstaller MSYS2-DevKit) | wxWidgets >= 3.2     |
-| Linux (tested; any AMD-64 distribution)<br>(most likely also i686 and ARM) | Ruby >= 2.5                                 | wxWidgets >= 3.2     |
-| MacOS >= 10.10 using Cocoa (tested on AMD-64 and ARM64 M2 Chip)            | Ruby >= 2.5                                 | wxWidgets >= 3.2     |
+| Platform                                                                                                                          | Ruby version(s)                                     | wxWidgets version(s) |
+|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|----------------------|
+| Windows 10 (tested)<br>(most likely also Windows 11)                                                                              | Ruby >= 2.5<br>(RubyInstaller MSYS2-DevKit)         | wxWidgets >= 3.2     |
+| Linux (tested; all major 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     |
 
 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
@@ -111,30 +111,41 @@ on legacy systems (eg Windows 98, Mac OS 9).
 
 wxRuby3 is distributed as a Ruby gem on [RubyGems](https://rubygems.org).<br>
 Apart from a regular source-only version of the gem there is also a binary gem version for Windows 10 provided (for the 
-latest stable Ruby version at the time of publishing) which includes an embedded wxWidgets installation (also latest 
+latest stable Ruby release at the time of publishing) which includes an embedded wxWidgets installation (also latest 
 stable version). 
 
-Installing the binary gem version on Windows requires no additional software to be installed except for a supported 
-version of the Ruby interpreter.<br>
-To install the source-only gem the following software is required:
+The wxRuby3 gem provides a **worry-free** installation procedure for all supported platforms.  
 
-| Sofware                                       | Notes                                                                                                                                                                                                                           |
-|-----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Ruby                                          | A supported version of the Ruby interpreter needs to be installed.                                                                                                                                                              |
-| C++ compiler<br>(incl. dev tools like `make`) | On linux a recent version of the GNU C++ compiler (with c++-14 support) needs to be installed<br>On Windows the RubyInstaller MSYS2-Devkit needs to be installed<br>On MacOS XCode with commandline tools needs to be installed |
-| Git version control toolkit                   |                                                                                                                                                                                                                                 |
-| SWIG >= 3.0.12                                | On MacOS install with Homebrew                                                                                                                                                                                                  |
-| Doxygen (>= 1.9.1)                            | On MacOS install with Homebrew                                                                                                                                                                                                  |
-| wxWidgets >= 3.2 (*OPTIONAL*)                 | On Linux most distributions provide system installable (development) packages for wxWidgets providing a supported version.<br>Alternatively you can fairly easily install your own preferred version manually.                  |    
+Installing the 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: 
 
-See the [INSTALL](INSTALL.md) document for more details.
+```shell
+gem install wxruby3
+```
 
-In case the prerequisites above are met the (source-only or binary) gem can be installed executing the following command:
+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:
 
 ```shell
-gem install wxruby3
+gem install wxruby3 && 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.
+
+> **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.
+
+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.