wxruby3 0.9.4 → 0.9.7

Sign up to get free protection for your applications and to get access to all the features.
Files changed (65) hide show
  1. checksums.yaml +4 -4
  2. data/INSTALL.md +315 -78
  3. data/README.md +32 -21
  4. data/ext/wxruby3/include/wxruby-ComboPopup.h +777 -0
  5. data/lib/wx/core/combo_ctrl.rb +171 -0
  6. data/lib/wx/core/ext.rb +22 -3
  7. data/lib/wx/doc/comboctrl.rb +128 -3
  8. data/lib/wx/doc/owner_drawn_combobox.rb +5 -1
  9. data/lib/wx/version.rb +1 -1
  10. data/lib/wx/wxruby/base.rb +6 -4
  11. data/lib/wx/wxruby/cmd/sampler.rb +39 -29
  12. data/lib/wx/wxruby/cmd/setup.rb +122 -0
  13. data/lib/wx/wxruby/cmd/test.rb +56 -6
  14. data/rakefile +14 -0
  15. data/rakelib/bin.rake +48 -0
  16. data/rakelib/bin.rb +62 -0
  17. data/rakelib/build.rb +11 -7
  18. data/rakelib/config.rake +3 -1
  19. data/rakelib/configure.rb +28 -8
  20. data/rakelib/doc.rake +3 -1
  21. data/rakelib/gem.rake +169 -0
  22. data/rakelib/gem.rb +82 -0
  23. data/rakelib/install.rb +2 -0
  24. data/rakelib/lib/config/linux.rb +24 -2
  25. data/rakelib/lib/config/macosx.rb +16 -0
  26. data/rakelib/lib/config/mingw.rb +133 -9
  27. data/rakelib/lib/config/pkgman/arch.rb +53 -0
  28. data/rakelib/lib/config/pkgman/base.rb +169 -0
  29. data/rakelib/lib/config/pkgman/debian.rb +66 -0
  30. data/rakelib/lib/config/pkgman/macosx.rb +183 -0
  31. data/rakelib/lib/config/pkgman/rhel.rb +54 -0
  32. data/rakelib/lib/config/pkgman/suse.rb +54 -0
  33. data/rakelib/lib/config/unixish.rb +36 -19
  34. data/rakelib/lib/config.rb +254 -61
  35. data/rakelib/lib/core/include/funcall.inc +2 -1
  36. data/rakelib/lib/core/package.rb +47 -49
  37. data/rakelib/lib/director/comboctrl.rb +104 -3
  38. data/rakelib/lib/director/defs.rb +1 -3
  39. data/rakelib/lib/director/gdicommon.rb +5 -0
  40. data/rakelib/lib/director/menu_item.rb +1 -1
  41. data/rakelib/lib/director/num_validator.rb +5 -7
  42. data/rakelib/lib/director/owner_drawn_combobox.rb +1 -0
  43. data/rakelib/lib/director/persistent_window.rb +2 -2
  44. data/rakelib/lib/director/pgeditor.rb +1 -1
  45. data/rakelib/lib/director/pgproperties.rb +3 -3
  46. data/rakelib/lib/director/pgproperty.rb +5 -1
  47. data/rakelib/lib/director/richtext_style_listbox.rb +5 -0
  48. data/rakelib/lib/director/sizer.rb +1 -1
  49. data/rakelib/lib/director/window.rb +4 -0
  50. data/rakelib/lib/extractor/module.rb +15 -0
  51. data/rakelib/lib/generate/doc/combo_ctrl.yaml +135 -0
  52. data/rakelib/lib/generate/doc/file_dialog_customize_hook.yaml +62 -0
  53. data/rakelib/lib/generate/doc/file_system.yaml +28 -0
  54. data/rakelib/lib/generate/doc.rb +29 -14
  55. data/rakelib/lib/generate/interface.rb +16 -6
  56. data/rakelib/lib/swig_runner.rb +18 -15
  57. data/rakelib/lib/typemap/combo_popup.rb +42 -0
  58. data/rakelib/prepost.rake +9 -4
  59. data/rakelib/yard/templates/default/fulldoc/html/css/wxruby3.css +14 -0
  60. data/rakelib/yard/templates/default/fulldoc/html/setup.rb +5 -5
  61. data/rakelib/yard/yard/relative_markdown_links.rb +7 -1
  62. data/tests/test_combo_ctrl.rb +196 -0
  63. metadata +28 -17
  64. data/ext/mkrf_conf_srcgem.rb +0 -67
  65. data/rakelib/run.rake +0 -52
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 59f48a6760484b863b4f3255bf866ecbd18faa5c0488fd40c6379bda58747299
4
- data.tar.gz: f131b88dab9c1994d98ae2fede1021308a539d298b6743c67a62ffc679748f0e
3
+ metadata.gz: 4d5a9a4c753ce46aa02eddc50cd51d51928a7e00b25172d2eae30ad4a2a87547
4
+ data.tar.gz: 36e5955935cf757e5aca26cf2df1b0ef3821e1c9a353508149ef4e0d95e2caa3
5
5
  SHA512:
6
- metadata.gz: 9f5a04f23e4978c856f79a8d2393d2cb08e2c4ce971fb915123cefb5ea2ee92a6fca38b3c7ccbc456c1e07480158dae5191635a9861cdcb5d7919be5f3c9e169
7
- data.tar.gz: ee935202f9fb3ef7af42da60b4311725c584485548f35c55b6f12ae4fa2b410740fc117b718134052a7aeb915ba7d2140cd096bc3f20a2ab1a1b5e30e82234b5
6
+ metadata.gz: fbf51eea1ad3411d80f3f01c8d08f601b04096e3cd36dae6eb29d073157b87dd430cda87a73b89430d5fddc64a8b43ba29e3e45f28a201b180b0bd87ead3ccad
7
+ data.tar.gz: ddd00e990557c587970ff0326eed3e61376ef74de243e7a1795cb7238d3aba06a2da15e4caa8b5438c6c34931ded3b486dbaea955e79cbf91b803013d732b4b4
data/INSTALL.md CHANGED
@@ -4,28 +4,104 @@
4
4
 
5
5
  # Installation of wxRuby3
6
6
 
7
- Below are installation instructions for Linux, Windows, and Mac (both AMD64 and ARM64).
7
+ ## Default installation
8
8
 
9
- ## Minimal requirements for installing wxRuby3
9
+ The wxRuby3 gem provides a **worry-free** installation for all supported platforms.
10
10
 
11
- The minimal requirements for installing any source based setup (gem, source package or Github clone) of wxRuby3 are:
11
+ The default gem installation commands
12
+ ```shell
13
+ gem install wxruby3
14
+ ```
15
+
16
+ for Windows and
17
+
18
+ ```shell
19
+ gem install wxruby3 && wxruby setup
20
+ ```
21
+ for Linux and MacOSX (see Note below) and Windows (if installing for Ruby releases older than the latest stable release)
22
+ should always result in a successfully installed wxRuby3 version.<br>
23
+ Just follow the (very few and in some cases none) prompts at the start of the setup procedure and sit back and relax.
24
+
25
+ > **NOTE**<br>
26
+ > Currently installing the wxRuby3 gem for the system supplied Ruby on MacOSX systems does not work.<br>
27
+ > The user is therefor required to install a Ruby interpreter using either [MacPorts](https://www.macports.org/) (both
28
+ > privileged and user installations are supported) or [Homebrew](https://brew.sh/) or Ruby installers/version managers
29
+ > like [ruby-install](https://github.com/postmodern/ruby-install) or [RVM](https://rvm.io) (only user installations supported) .
30
+
31
+ [Below](INSTALL.md#installing-software-requirements) more details regarding the software requirements for wxRuby3, the
32
+ setup procedure and various options to tweak and customize the installation (including platform specific details for
33
+ Linux, Windows and MacOSX) are described.
34
+
35
+ ## Bundled CLI
36
+
37
+ Installing the wxRuby3 gem will also install the bundled `wxruby` CLI binary.
38
+
39
+ For source gem installations the CLI will initially only provide the *setup* command.
40
+
41
+ For binary gem installations and successfully set up source gem installations the *setup* command is replaced by other
42
+ utility commands providing the ability to run the bundled regression tests and access (run or copy) the bundled examples.<br>
43
+ Run the following command to see the available options at any time:
44
+
45
+ ```shell
46
+ wxruby --help
47
+ ```
48
+
49
+ ## Software requirements for wxRuby3
50
+
51
+ The software requirements for setting up a wxRuby3 runtime environment are:
52
+
53
+ | Sofware | Notes |
54
+ |-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
55
+ | 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. |
56
+ | 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. |
57
+ | 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. |
58
+ | Doxygen (>= 1.9.1) | Required for building the wxRuby3 extension libraries for a source based installation. [**1**] |
59
+ | SWIG >= 3.0.12 | Required for building the wxRuby3 extension libraries for a source based installation. [**2**] |
60
+ | Patchelf (Linux) or install_name_tool (OSX) | Required for setting up embedded wxWidgets libraries. [**3**] |
61
+ | wxWidgets (>= 3.2) | Runtime libraries required for any wxRuby3 installation (either from embedded wxWidgets installation or a system or user installation; see below). |
62
+
63
+ Except for Ruby itself all other software requirements can be handled by the **worry-free**, fully automated installation procedure of wxRuby3.
64
+
65
+ But of course any of these requirements can also be fulfilled explicitly with self controlled steps **before** starting the
66
+ wxRuby3 installation procedure. See the platform specific sections of [Installing software requirements](INSTALL.md#installing-software-requirements) for details on
67
+ how to go about that.
68
+
69
+ [**1**] The wxRuby3 build process needs doxygen to generated XML files containing wxWidgets interface specs which are used to
70
+ generate interface definitions for SWIG
71
+
72
+ [**2**] The wxRuby3 build process uses SWIG to generate C++ source code for the wrapper interfaces from
73
+ which the native extensions are compiled. Both SWIG version 3 and version 4 are supported.
12
74
 
13
- | Sofware | Notes |
14
- |-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
15
- | Ruby | A supported version of the Ruby interpreter needs to be installed. |
16
- | 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> |
17
- | Git version control toolkit | |
18
- | SWIG >= 3.0.12 | On MacOS install Homebrew (https://brew.sh) and than <code>brew install swig</code> |
19
- | Doxygen (>= 1.9.1, <= 1.9.6) | Doxygen > 1.9.6 has changes that cause problems with the wxWidgets doxygen files.<br>On MacOS: <code>brew tap mcorino/wxruby3</code> and than `brew install doxygen@1.9.6` (default brew recipe installs 1.9.7) |
20
- | wxWidgets (>= 3.2) | See the <b>wxWidgets installation</b> section below. |
75
+ [**3**] The wxRuby3 build process uses these tools to adjust the shared library load paths ('rpath' setting) in case of embedded wxWidgets libraries.
21
76
 
22
- The wxRuby3 build process requires `git` to clone a copy of the wxWidgets Github repository to extract the interface
23
- specifications from.<br>
24
- The wxRuby3 build process needs doxygen to generated XML files containing wxWidgets interface specs which are used to
25
- generate SWIG interface definitions from which SWIG to generates C++ source code for the wrapper interfaces from
26
- which the native extension is compiled.
77
+ ### wxWidgets installation variants
27
78
 
28
- ## Installation of a wxRuby3 Gem
79
+ wxRuby3 can be built and installed for 3 different types of wxWidgets installations:
80
+
81
+ 1. A system installation of wxWidgets libraries and development files.<br>
82
+ This actually only has real meaning on Linux where this corresponds with installing distribution provided packages.
83
+ On MacOSX and Windows this only means that libraries are installed (as a user addon since no standard distribution
84
+ packages exist for these platforms but possibly using the administrator account) such that they can be loaded using
85
+ the default library load paths and the `wx-config` tool is executable from the default search path.<br>
86
+ This kind of installation is automatically detected and no special setup options are required for the wxRuby3 installation procedure.
87
+ 2. A user installation of wxWidgets libraries and development files.<br>
88
+ This is the most likely scenario for a development setup of wxRuby3 where a special (possibly updated) release of
89
+ wxWidgets is installed to build wxRuby3 for.<br>
90
+ In this case the libraries and development files are most likely not found in standard locations and the wxRuby3
91
+ installation procedure will require specific options to have these locations provided.
92
+ 3. An 'embedded' installation of wxWidgets setup by the wxRuby3 installation procedure.<br>
93
+ This is the default when the installation procedure does not detect a (compatible!) system installation or if an
94
+ option has been provided explicitly specifying to install an embedded wxWidgets version.
95
+
96
+ Please note that in case of option **2** the user is responsible to make sure the wxWidgets shared libraries can be
97
+ found by the system's dynamic loader at runtime.
98
+
99
+ As described with option **3** a wxWidgets system installation must be compatible (>= version 3.2) to be selected. In case
100
+ the installed version does not meet this requirement it is ignored as if not installed.
101
+
102
+ For more information on how to install wxWidgets see the [Installing software requirements](INSTALL.md#installing-software-requirements) section below.
103
+
104
+ ## wxRuby3 gem installation details
29
105
 
30
106
  The wxRuby3 project provides gems on [RubyGems](https://rubygems.org) which can be installed with the
31
107
  standard `gem install` command line this:
@@ -34,92 +110,253 @@ standard `gem install` command line this:
34
110
  gem install wxruby3
35
111
  ```
36
112
 
37
- On Linux systems this will install the source based gem which will automatically build the native wxruby3 extension
38
- for the platform on which wxRuby3 is being installed.
113
+ 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
114
+ for the platform on which wxRuby3 is being installed.<br>
39
115
  On Windows systems a prebuilt binary gem is available for the latest stable release(s) of [RubyInstaller](https://rubyinstaller.org)
40
116
  installed rubies that will be installed by default if installing for that platform (including an embedded, latest
41
117
  stable version, wxWidgets installation).<br>
42
- Alternatively the source gem can be installed on Windows by installing with explicit platform specification like this:
118
+ Alternatively the source gem can be installed on Windows by installing with an explicit platform specification like this:
43
119
 
44
120
  ```shell
45
121
  gem install wxruby3 --platform=ruby
46
122
  ```
47
123
 
48
- When installing the source gem the minimal requirements listed above apply.
124
+ > The result of installing the gem on a Linux platform should be something like this:
125
+ > ```
126
+ > $ gem install wxruby3
127
+ >
128
+ > The wxRuby3 Gem has been successfully installed.
129
+ > Before being able to use wxRuby3 you need to run the post-install setup process
130
+ > by executing the command 'wxruby setup'.
131
+ >
132
+ > Run 'wxruby setup -h' to see information on the available commandline options.
133
+ >
134
+ > Successfully installed wxruby3-0.9.5
135
+ > Parsing documentation for wxruby3-0.9.5
136
+ > Installing ri documentation for wxruby3-0.9.5
137
+ > Done installing documentation for wxruby3 after 10 seconds
138
+ > 1 gem installed
139
+ > ```
140
+
141
+ As said, on Linux and MacOSX systems (also on Windows when installing the source gem) an additional command is required
142
+ to build the actual wxRuby3 extension libraries for the platform which is a wxRuby3 CLI command installed by the gem:
49
143
 
50
- On MacOS, if wxWidgets was not available, you can pull in the latest wxWidgets and build it by adding the `WITH_WXWIN=1` option:
144
+ ```shell
145
+ wxruby setup
146
+ ```
147
+
148
+ The wxRuby3 CLI `wxruby` is installed by all wxRuby3 gems. In case of the source gem initially the CLI will provide only
149
+ a single command `wxruby setup` to finish wxRuby3 extension (build and) installation.
150
+
151
+ For most (user) installations the default setup command as shown above will suffice nicely. In this case the setup
152
+ (or installation) procedure will analyze the system to see if it meets the software requirements described above and if not
153
+ collect information on what is missing and needs to be added to finish the wxRuby3 installation. In order this would check:
154
+
155
+ - availability of the `doxygen` tool
156
+ - availability of the `swig` tool
157
+ - availability of the `git` tool
158
+ - availability of a (compatible) system installation of wxWidgets
159
+ - development tools and libraries required for an embedded wxWidgets installation (in case no system installation is used)
160
+
161
+ If any required software needs to be added the setup procedure will ask consent (showing what it intends to do) and, if given,
162
+ install the missing software using appropriate tooling for the platform (on Linux standard distribution installers which
163
+ may require a 'sudo' password and on MacOSX using either [MacPorts](https://www.macports.org/) or [Homebrew](https://brew.sh/)).
164
+
165
+ > Running the setup command will look something like this:
166
+ > ```
167
+ > $ wxruby setup
168
+ >
169
+ > ---
170
+ > Now running wxRuby3 post-install setup.
171
+ > This will (possibly) install required software, build the wxWidgets libraries,
172
+ > build the native wxRuby3 extensions and generate the wxRuby3 reference documentation.
173
+ > Please be patient as this may take quite a while depending on your system.
174
+ > ---
175
+ >
176
+ > [ --- ATTENTION! --- ]
177
+ > wxRuby3 requires some software packages to be installed before being able to continue building.
178
+ > If you like these can be automatically installed next (if you are building the source gem the
179
+ > software will be removed again after building finishes).
180
+ > Do you want to have the required software installed now? [yN] :
181
+ > ```
182
+
183
+ The initial message shown (between lines starting with '---' ) is indicative of what is going to happen depending
184
+ on options passed to the setup command.<br>
185
+ Building the wxRuby3 native extensions and generating reference documentation will always happen.
186
+
187
+ ### Disable prompting for automatic install
188
+
189
+ To prevent having the setup procedure asking consent the setup procedure can be started with the `--autoinstall` option
190
+ like this:
51
191
 
52
192
  ```shell
53
- gem install wxruby3 -- WITH_WXWIN=1
193
+ wxruby setup --autoinstall
54
194
  ```
55
195
 
56
- ### wxWidgets installation
57
-
58
- Also a wxWidgets installation (version 3.2 or later) is required for which there are multiple options.
59
-
60
- 1. System installed wxWidgets version (including development package)<br/>
61
- <br/>
62
- This is the default method used when installing the source gem without any options.<br>
63
- The wxRuby build procedure will determine the availability and version of wxWidgets by locating and calling
64
- the `wx-config` utility script. In case no (compatible) wxWidgets version is found installation ends with an error.<br>
65
- Please note that even with this method a copy of the wxWidgets project will be checked out from GitHUb as the wxRuby3
66
- build procedure requires access to the wxWidgets interface specification sources which are not normally part of any of
67
- the standard distribution packages.<br/>
68
- <br/>
69
- On MacOS, you can install wxWidgets via [Homebrew](https://brew.sh/):
70
- ```shell
71
- brew install wxwidgets
72
- ```
73
- Afterwards, you can install the Ruby gem and it will detect wxWidgets in the system automatically:
74
- ```shell
75
- gem install wxruby3
76
- ```
77
-
78
- 2. User installed wxWidgets version<br>
79
- <br>
80
- In case the system being installed on does not provide (a compatible) wxWidgets version or a specific (possibly updated)
81
- wxWidgets version is required the source gem can be installed using a user installed version like this (where the
82
- `WXWIN` path should provide the location where the wxWidgets binaries are installed under `<wxwin path>/bin`):<br>
83
- ```shell
84
- gem install wxruby3 -- WXWIN=/path/to/wx/install
85
- ```
86
-
87
- 3. Automatic installed, embedded, wxWidgets version<br>
88
- <br>
89
- This is the easiest method when the system being installed on does not provide (a compatible) wxWidgets version (and
90
- no specific user defined version is required) and can be used by installing the source gem like this (which will
91
- cause automatic checkout and building of the latest stable wxWidgets release (>= 3.2) from GitHub:
92
- ```shell
93
- gem install wxruby3 -- WITH_WXWIN=1
94
- ```
95
-
96
- In case of option **2** it is also possible to do the doxygen XML generation as part of the wxWidgets user installation
97
- and use that for the gem installation. In that case the user is required to generate the XML interface specs using the
98
- `regen` script found in the `docs/doxygen` folder of the wxWidgets installation after which the XML output folder can be
99
- provided to the gem installation as follows:
196
+ Note that on Linux that may still present a prompt in case the `sudo` command requires a password.
197
+
198
+ ### Prevent automatic installation of software requirements
199
+
200
+ To prevent the setup procedure from considering to automatically install (with or without prompting) any missing software
201
+ requirements the setup procedure can be started with the `--no-autoinstall` option like this:
100
202
 
101
203
  ```shell
102
- gem install wxruby3 -- WXWIN=/path/to/wx/install WXXML=/path/to/wx/doxygen/xml
204
+ wxruby setup --no-autoinstall
103
205
  ```
104
206
 
105
- Please also not that in case of option **2** the user is responsible to make sure the wxWidgets shared libraries can be
106
- found by the system's dynamic loader at runtime.
207
+ The setup procedure will still analyze the system for available software requirements and if it finds any missing it
208
+ will end the procedure and show a message of what it found missing.
107
209
 
108
- > **NOTE:** Be patient when installing the source gem. Building wxRuby3 takes a while and when wxWidgets is included event more.
210
+ ### Force embedded wxWidgets installation
109
211
 
110
- > **NOTE:** Be aware that for prerelease versions of the gem you should add the `--pre` argument to the `gem install` command.
212
+ To prevent the setup procedure of using any system installed wxWidgets version the setup procedure can be started with
213
+ the `--with-wxwin` option like this:
111
214
 
112
- ### Bundled CLI
215
+ ```shell
216
+ wxruby setup --with-wxwin
217
+ ```
113
218
 
114
- Installing the wxRuby3 gem will also install the bundled `wxruby` CLI binary.
219
+ This will force the setup procedure to build and install an embedded wxWidgets version for wxRuby3.
115
220
 
116
- Currently this binary can be used to run the bundled regression tests and access (run or copy) the bundled examples.
117
- Run the following command to see the options:
221
+ ### Setup with user installed wxWidgets
222
+
223
+ In case of a (custom) user installation of wxWidgets the `--wxwin` (and optionally `--wxxml`) option(s) can be used to
224
+ start the setup procedure to build for this installation like this:
118
225
 
119
226
  ```shell
120
- wxruby --help
227
+ wxruby setup --wxwin=/my/custom/wxWidgets
228
+ ```
229
+
230
+ If the wxWidgets installation also holds the doxygen generated XML interface specification files in the default location
231
+ (`docs/doxygen/out/xml`) these will be used to build the wxRuby3 extensions. If not, the setup procedure will create these
232
+ files itself (from a freshly cloned copy of the wxWidgets repository).<br>
233
+ If the XML files have been created in a non-standard location that can be passed on to the setup procedure like this:
234
+
235
+ ```shell
236
+ wxruby setup --wxwin=/my/custom/wxWidgets --wxxml=/my/alternate/wxWidgets/xml
237
+ ```
238
+
239
+ > **NOTE**<br>
240
+ > Please be aware that in case of building wxRuby3 for a user installation of wxWidgets the user is also
241
+ > responsible for making sure the wxRuby3 extension library can find the wxWidgets libraries at runtime (normally this
242
+ > requires updating the standard shared library search path for the platform).
243
+
244
+ ### Setup with customized tool paths
245
+
246
+ If for whatever reason the required development tools `doxygen`, `swig` and/or `git` have been installed in a location
247
+ not in the standard executable search path the full path to these tools can be passed on the setup procedure using the
248
+ `--doxygen`, `--swig` and/or `--git` options like this:
249
+
250
+ ```shell
251
+ wxruby setup --doxygen=/my/path/to/doxygen
252
+ ```
253
+
254
+ ### Redirect log to customized path
255
+
256
+ The setup procedure will log full build results to a file setup.log at the location where the gem contents is stored.
257
+ If the setup fails the error message will display the log file location and by default if the setup succeeds the log
258
+ file is deleted.<br>
259
+ To redirect the log file to be stored at an alternate location an not be deleted in any case the `--log` option can be
260
+ used like this:
261
+
262
+ ```shell
263
+ wxruby setup --log=/my/log/folder
121
264
  ```
122
265
 
266
+ In this case the log file would be created as `/my/log/folder/setup.log`.
267
+
268
+ ## Installing software requirements
269
+
270
+ As described, instead of having the wxRuby3 setup procedure install the software requirements automatically these can
271
+ also be installed beforehand.
272
+
273
+ The following sections give some information how to accomplish that for the various supported platforms.
274
+
275
+ ### Installing software requirements on Windows
276
+
277
+ On Windows these software requirements are only needed when **not** installing the binary gem.
278
+
279
+ #### Compiler
280
+
281
+ Download and install the [RubyInstaller MSYS2-Devkit](https://rubyinstaller.org/downloads/) which includes both Ruby
282
+ and a full set of development tools like GNU C++, make etc.
283
+
284
+ #### Doxygen
285
+
286
+ Download the Windows installer [here](https://doxygen.nl/download.html).
287
+
288
+ #### SWIG
289
+
290
+ Download the Windows archive [here](https://www.swig.org/download.html).
291
+
292
+ #### Git
293
+
294
+ Any Windows compatible Git version will do like [this](https://gitforwindows.org/) one.
295
+
296
+ #### wxWidgets
297
+
298
+ See the information on the wxWidgets website [here](https://wxwidgets.org/downloads/). Download and install either
299
+ a binary installation compatible with the MingW64 compiler version available from the RubyInstaller MSYS2-Devkit
300
+ installation (make sure to get this right or bad things will happen) or download a source package and build using the
301
+ compiler tools from the RubyInstaller MSYS2-Devkit installation. See [here](https://docs.wxwidgets.org/3.2/overview_install.html) for information about
302
+ building wxWidgets from source.
303
+
304
+ ### Installing software requirements on MacOSX
305
+
306
+ #### Compiler
307
+
308
+ Install the XCode commandline tools using the command <code>sudo xcode-select --install</code>.
309
+
310
+ #### Doxygen
311
+
312
+ Depending on how you installed Ruby on your MacOS system use [Homebrew](https://brew.sh) with the command <code>brew install doxygen</code>
313
+ or use [MacPorts](https://www.macports.org/) with the command <code>port install doxygen</code>.
314
+
315
+ #### SWIG
316
+
317
+ Depending on how you installed Ruby on your MacOS system use [Homebrew](https://brew.sh) with the command <code>brew install swig</code>
318
+ or use [MacPorts](https://www.macports.org/) with the command <code>port install swig</code>.
319
+
320
+ #### Git
321
+
322
+ Is included in the XCode commandline tools.
323
+
324
+ #### wxWidgets
325
+
326
+ Either install a compatible wxWidgets version (>= 3.2) with the package manager of choice (Homebrew or MacPorts) if available
327
+ or download and build a source package from [here](https://wxwidgets.org/downloads/) (alternatively the wxWidgets Github
328
+ repository could be cloned). See [here](https://docs.wxwidgets.org/3.2/overview_install.html) for information about
329
+ building wxWidgets from source.
330
+
331
+ ### Installing software requirements on Linux
332
+
333
+ #### Compiler
334
+
335
+ Install the GNU C++ compiler and common development tools like 'make' using the system provided package management.
336
+
337
+ #### Patchelf
338
+
339
+ Install the patchelf tool using the system provided package management.
340
+
341
+ #### Doxygen
342
+
343
+ Install the doxygen tool using the system provided package management.
344
+
345
+ #### SWIG
346
+
347
+ Install the swig tool using the system provided package management.
348
+
349
+ #### Git
350
+
351
+ Install the git tool using the system provided package management.
352
+
353
+ #### wxWidgets
354
+
355
+ Either install a compatible wxWidgets version (>= 3.2) with the system provided package management if available
356
+ or download and build a source package from [here](https://wxwidgets.org/downloads/) (alternatively the wxWidgets Github
357
+ repository could be cloned). See [here](https://docs.wxwidgets.org/3.2/overview_install.html) for information about
358
+ building wxWidgets from source.
359
+
123
360
  ## Building from source
124
361
 
125
362
  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
132
369
  The wxRuby3 project provides a Rake based build system. Call `rake help` to get an overview of the available commands.
133
370
  As mentioned there the `rake configure` command is required as the very first command. Call `rake configure[--help]` to
134
371
  get a detailed overview of the options for this command.<br>
135
- As with the source gem 3 options exist for the wxWidgets installation which will have to be specified to `rake configure`.
372
+ As with the source gem 3 options exist for the wxWidgets installation for which details can be specified to `rake configure`.
136
373
 
137
374
  When wxRuby3 has been configured the extensions can be build by calling the `rake build` command. The wxRuby3 build
138
375
  commands are executed using parallel task execution by default.
data/README.md CHANGED
@@ -96,11 +96,11 @@ of these products.
96
96
 
97
97
  Currently the following are fully supported:
98
98
 
99
- | Platform | Ruby version(s) | wxWidgets version(s) |
100
- |----------------------------------------------------------------------------|---------------------------------------------|----------------------|
101
- | Windows 10 (tested)<br>(most likely also Windows 11) | Ruby >= 2.5<br>(RubyInstaller MSYS2-DevKit) | wxWidgets >= 3.2 |
102
- | Linux (tested; any AMD-64 distribution)<br>(most likely also i686 and ARM) | Ruby >= 2.5 | wxWidgets >= 3.2 |
103
- | MacOS >= 10.10 using Cocoa (tested on AMD-64 and ARM64 M2 Chip) | Ruby >= 2.5 | wxWidgets >= 3.2 |
99
+ | Platform | Ruby version(s) | wxWidgets version(s) |
100
+ |-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|----------------------|
101
+ | Windows 10 (tested)<br>(most likely also Windows 11) | Ruby >= 2.5<br>(RubyInstaller MSYS2-DevKit) | wxWidgets >= 3.2 |
102
+ | 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 |
103
+ | MacOS >= 10.10 using Cocoa (tested on AMD-64 and ARM64 M2 Chip) | Ruby >= 2.5 (MacPorts, Homebrew, ruby-install, RVM) | wxWidgets >= 3.2 |
104
104
 
105
105
  Support for other platforms is not being actively developed at present,
106
106
  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).
111
111
 
112
112
  wxRuby3 is distributed as a Ruby gem on [RubyGems](https://rubygems.org).<br>
113
113
  Apart from a regular source-only version of the gem there is also a binary gem version for Windows 10 provided (for the
114
- latest stable Ruby version at the time of publishing) which includes an embedded wxWidgets installation (also latest
114
+ latest stable Ruby release at the time of publishing) which includes an embedded wxWidgets installation (also latest
115
115
  stable version).
116
116
 
117
- Installing the binary gem version on Windows requires no additional software to be installed except for a supported
118
- version of the Ruby interpreter.<br>
119
- To install the source-only gem the following software is required:
117
+ The wxRuby3 gem provides a **worry-free** installation procedure for all supported platforms.
120
118
 
121
- | Sofware | Notes |
122
- |-----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
123
- | Ruby | A supported version of the Ruby interpreter needs to be installed. |
124
- | 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 |
125
- | Git version control toolkit | |
126
- | SWIG >= 3.0.12 | On MacOS install with Homebrew |
127
- | Doxygen (>= 1.9.1, <= 1.9.6) | Doxygen > 1.9.6 has changes that cause problems with the wxWidgets doxygen files. |
128
- | 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. |
119
+ Installing the binary gem version on Windows (which is the default when installing for the latest stable Ruby release for
120
+ that platform) requires no additional installation steps and/or additional software to be installed except for a supported
121
+ version of the Ruby interpreter. So for this platform the following command is all it takes to get up and running:
129
122
 
130
- See the [INSTALL](INSTALL.md) document for more details.
123
+ ```shell
124
+ gem install wxruby3
125
+ ```
131
126
 
132
- In case the prerequisites above are met the (source-only or binary) gem can be installed executing the following command:
127
+ For the platforms requiring a source based installation (Linux and MacOSX as well as Windows for older Ruby releases
128
+ or when explicitly selecting source based install) an additional (simple) setup step is required to finish installation.
129
+ For these platforms the full installation sequence would be:
133
130
 
134
131
  ```shell
135
- gem install wxruby3
132
+ gem install wxruby3 && wxruby setup
136
133
  ```
137
134
 
135
+ The second part of this command sequence is a fully automated setup procedure provided by the wxRuby3 **CLI** installed with
136
+ the gem. This procedure (by default) will analyze your system and install (after asking your consent) any missing software
137
+ requirements and build the wxRuby3 extension libraries (including a embedded copy of wxWidgets if necessary). It may take
138
+ quite a while depending on your system but you can mostly sit back and relax.
139
+
140
+ > **NOTE**<br>
141
+ > A source based installation requires the availability of the Ruby development headers. User installed Rubies in most cases
142
+ > will already include those but (especially on Linux) system installed Rubies may require having an additional '-dev/-devel'
143
+ > package installed.
144
+
145
+ This install procedure can of course be tweaked and customized with commandline arguments.
146
+ See the [INSTALL](INSTALL.md) document for more details.
147
+
148
+
138
149
  ### Where can I ask a question, or report a bug?
139
150
 
140
151
  Use GitHUb Issues.
@@ -204,7 +215,7 @@ Several years of development have passed for wxWidgets and Ruby respectively,
204
215
  improving code quality, adding new classes and new language features.
205
216
  In 2022 I finally found the time and the inspiration to pick up this project
206
217
  with the idea of reviving it to build some applications I had in mind.
207
- wxRuby 3 intents to provide Ruby interfaces for all relevant (!) wxWidget
218
+ wxRuby 3 intends to provide Ruby interfaces for all relevant (!) wxWidget
208
219
  classes of the latest version 3.2 and beyond.
209
220
  Building on the experiences of the previous wxRuby (2) developments as well
210
221
  as the wxPython Phoenix project it is expected to provide a better and more