wxruby3 0.9.5 → 0.9.8
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/INSTALL.md +440 -84
- data/README.md +40 -23
- data/ext/mkrf_conf_ext.rb +68 -0
- data/lib/wx/core/ext.rb +22 -3
- data/lib/wx/core/secret_store.rb +38 -0
- data/lib/wx/doc/extra/02_lifecycles.md +4 -4
- data/lib/wx/doc/extra/14_config.md +1 -1
- data/lib/wx/doc/secret_store.rb +55 -0
- data/lib/wx/version.rb +1 -1
- data/lib/wx/wxruby/base.rb +8 -8
- data/lib/wx/wxruby/cmd/check.rb +182 -0
- data/lib/wx/wxruby/cmd/sampler.rb +39 -29
- data/lib/wx/wxruby/cmd/setup.rb +125 -0
- data/lib/wx/wxruby/cmd/test.rb +56 -6
- data/rakelib/bin.rake +48 -0
- data/rakelib/bin.rb +62 -0
- data/rakelib/build.rb +11 -7
- data/rakelib/config.rake +3 -1
- data/rakelib/configure.rb +63 -35
- data/rakelib/doc.rake +3 -1
- data/rakelib/gem.rake +199 -0
- data/rakelib/gem.rb +334 -0
- data/rakelib/install.rb +5 -3
- data/rakelib/lib/config/{cygwin.rb → freebsd.rb} +1 -1
- data/rakelib/lib/config/linux.rb +26 -2
- data/rakelib/lib/config/macosx.rb +58 -11
- data/rakelib/lib/config/mingw.rb +134 -10
- data/rakelib/lib/config/pkgman/linux.rb +144 -0
- data/rakelib/lib/config/pkgman/macosx.rb +122 -0
- data/rakelib/lib/config/unixish.rb +47 -20
- data/rakelib/lib/config/{netbsd.rb → unknown.rb} +3 -2
- data/rakelib/lib/config.rb +301 -88
- data/rakelib/lib/core/package.rb +47 -49
- data/rakelib/lib/director/aui_manager.rb +1 -1
- data/rakelib/lib/director/dialog.rb +8 -0
- data/rakelib/lib/director/gdicommon.rb +1 -2
- data/rakelib/lib/director/grid_ctrl.rb +2 -2
- data/rakelib/lib/director/richtext_composite_object.rb +2 -4
- data/rakelib/lib/director/secret_store.rb +117 -0
- data/rakelib/lib/director/tree_event.rb +2 -2
- data/rakelib/lib/generate/doc/secret_store.yaml +55 -0
- data/rakelib/lib/generate/doc.rb +29 -14
- data/rakelib/lib/generate/interface.rb +4 -2
- data/rakelib/lib/specs/interfaces.rb +1 -0
- data/rakelib/lib/swig_runner.rb +11 -11
- data/rakelib/lib/typemap/common.rb +10 -0
- data/rakelib/prepost.rake +17 -5
- data/rakelib/yard/templates/default/fulldoc/html/css/wxruby3.css +18 -0
- data/rakelib/yard/templates/default/fulldoc/html/setup.rb +5 -5
- data/rakelib/yard/yard/relative_markdown_links.rb +7 -1
- data/samples/sampler/sample.rb +2 -0
- data/tests/lib/wxapp_runner.rb +1 -1
- data/tests/test_config.rb +7 -4
- data/tests/test_secret_store.rb +83 -0
- metadata +46 -23
- data/ext/mkrf_conf_srcgem.rb +0 -67
- data/rakelib/run.rake +0 -52
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 5c45580184f8f7ee466f9ec158bcb9f28702f6674ab42abc735f7235cc3482bd
|
|
4
|
+
data.tar.gz: f22f78e25c135b2583bfd60a7712c1084b8be8b3550d695e1acf65eac19b2223
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 401ff95651f766ac947eba8a1a58a77be718182a473549f49eeee5b361a019051da88f529aec58bfe88dd46b5104dbae64a96eba5fa14d6a3e446fcece35c6f0
|
|
7
|
+
data.tar.gz: fe9f01627e61ddc1ff5c18936dbf71f1cf09fd7d6ce372b6cc25062051a3807b3e6a0fe59179753ce0a1f9577f856eefca58c0564d0860a6e607d14bba428606
|
data/INSTALL.md
CHANGED
|
@@ -4,122 +4,475 @@
|
|
|
4
4
|
|
|
5
5
|
# Installation of wxRuby3
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Default installation
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
The wxRuby3 gem provides a **worry-free** installation for all supported platforms.
|
|
10
10
|
|
|
11
|
-
The
|
|
11
|
+
The default gem installation command
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
13
|
+
```shell
|
|
14
|
+
gem install wxruby3
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
and the setup command
|
|
18
|
+
|
|
19
|
+
```shell
|
|
20
|
+
wxruby setup
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
for installations without prebuilt binary packages should always result in a successfully installed wxRuby3 version.
|
|
21
24
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
The
|
|
25
|
-
|
|
26
|
-
|
|
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
|
|
30
|
+
> supported) .
|
|
27
31
|
|
|
28
|
-
|
|
32
|
+
[Below](INSTALL.md#installing-software-requirements) more details regarding the software requirements for wxRuby3, the
|
|
33
|
+
setup procedure and various options to tweak and customize the installation (including platform specific details for
|
|
34
|
+
Linux, Windows and MacOSX) are described.
|
|
29
35
|
|
|
30
|
-
|
|
36
|
+
## Bundled CLI
|
|
37
|
+
|
|
38
|
+
Installing the wxRuby3 gem will also install the bundled `wxruby` CLI binary.
|
|
39
|
+
|
|
40
|
+
For source gem installations the CLI will initially only provide the `check` and `setup` commands.
|
|
41
|
+
|
|
42
|
+
For finalized installations (either from binary packages or source builds) the *setup* command is replaced by other
|
|
43
|
+
utility commands providing the ability to run the bundled regression tests and access (run or copy) the bundled examples.<br>
|
|
44
|
+
Run the following command to see the available options at any time:
|
|
45
|
+
|
|
46
|
+
```shell
|
|
47
|
+
wxruby -h
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Binary packages
|
|
51
|
+
|
|
52
|
+
The wxRuby3 gem installation process will by default attempt to match the current platform to any standard available
|
|
53
|
+
binary packages and if found install the matched package.
|
|
54
|
+
|
|
55
|
+
Binary packages are archives (custom format) containing prebuilt (extension) library artifacts for a single specific
|
|
56
|
+
platform. Any such platform is identified by:
|
|
57
|
+
|
|
58
|
+
- CPU architecture (x86_64, ARM64, etc.)
|
|
59
|
+
- Operating system type (linux, darwin, windows, etc.)
|
|
60
|
+
- OS distribution and release number (except for windows)
|
|
61
|
+
- Ruby ABI version (i.e. {major}.{minor})
|
|
62
|
+
|
|
63
|
+
The standard available binary packages provide both the wxRuby3 extension libraries as well as the embedded wxWidgets
|
|
64
|
+
libraries the extension libraries were built for.<br>
|
|
65
|
+
This is however not mandatory. User created binary packages can be built for separately installed (either distribution
|
|
66
|
+
or user provided) wxWidgets libraries.
|
|
67
|
+
|
|
68
|
+
### Standard packages
|
|
69
|
+
|
|
70
|
+
The standard release artifacts at [Github](https://github.com/mcorino/wxRuby3/releases) provide a selection of binary
|
|
71
|
+
packages for all supported OS platforms which are automatically built and uploaded for every release.<br>
|
|
72
|
+
The following tables lists the packages provided by the current wxRuby3 release process:
|
|
73
|
+
|
|
74
|
+
| OS | Distributions | Architectures | Rubies |
|
|
75
|
+
|---------|-------------------------------|-------------------------|----------------------------------------------------|
|
|
76
|
+
| Linux | OpenSuSE Leap (latest stable) | x86_64 <b>and</b> ARM64 | Distro provided Ruby <b>and</b> Latest stable Ruby |
|
|
77
|
+
| Linux | Fedora (latest stable) | x86_64 <b>and</b> ARM64 | Distro provided Ruby <b>and</b> Latest stable Ruby |
|
|
78
|
+
| Linux | Debian (latest stable) | x86_64 <b>and</b> ARM64 | Distro provided Ruby <b>and</b> Latest stable Ruby |
|
|
79
|
+
| Linux | Ubuntu (latest stable) | x86_64 <b>and</b> ARM64 | Distro provided Ruby <b>and</b> Latest stable Ruby |
|
|
80
|
+
| Windows | NA | x86_64 | Latest stable Ruby |
|
|
81
|
+
| OSX | MacOSX 12 | x86_64 <b>and</b> ARM64 | Latest stable Ruby |
|
|
82
|
+
| OSX | MacOSX 13 | x86_64 <b>and</b> ARM64 | Latest stable Ruby |
|
|
83
|
+
| OSX | MacOSX 14 | ARM64 | Latest stable Ruby |
|
|
84
|
+
|
|
85
|
+
### User created packages
|
|
86
|
+
|
|
87
|
+
Users can create their own wxRuby3 binary packages by building from source ([see here](#building-from-source)) and after
|
|
88
|
+
successfully having built the wxWidgets extension libraries execute the `rake binpkg` command.<br>
|
|
89
|
+
This creates two files in the `pkg` folder with names like<br>
|
|
90
|
+
`wxruby3_{distribution}_ruby{abi version}_v{wxruby version}_{os}_{arch}.pkg`<br>
|
|
91
|
+
and<br>
|
|
92
|
+
`wxruby3_{distribution}_ruby{abi version}_v{wxruby version}_{os}_{arch}.sha`<br>
|
|
93
|
+
where the `.pkg` file is the actual binary archive and the `.sha` file is the associated SHA256 digest signature of the
|
|
94
|
+
archive contents.
|
|
95
|
+
|
|
96
|
+
Both files are required for installation and should be located at the same path (either local path or http(s) url).<br>
|
|
97
|
+
[See here](#the-package-option) for information on how to use user created binary packages with the wxRuby3 gem installation process.
|
|
98
|
+
|
|
99
|
+
## Software requirements for wxRuby3
|
|
100
|
+
|
|
101
|
+
The software requirements for setting up a wxRuby3 runtime environment are:
|
|
102
|
+
|
|
103
|
+
| Sofware | Notes |
|
|
104
|
+
|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
105
|
+
| 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. |
|
|
106
|
+
| 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. |
|
|
107
|
+
| 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. |
|
|
108
|
+
| Doxygen (>= 1.9.1) | Required for building the wxRuby3 extension libraries for a source based installation. [**1**] |
|
|
109
|
+
| SWIG >= 3.0.12 | Required for building the wxRuby3 extension libraries for a source based installation. [**2**] |
|
|
110
|
+
| Patchelf (Linux) or install_name_tool (OSX) | Required for setting up embedded wxWidgets libraries. [**3**] |
|
|
111
|
+
| wxWidgets (>= 3.2) | Runtime libraries required for any wxRuby3 installation (either from embedded wxWidgets installation or a system or user installation; see below). |
|
|
112
|
+
|
|
113
|
+
Except for Ruby itself all other software requirements can be handled by the **worry-free**, fully automated installation procedure of wxRuby3.
|
|
114
|
+
|
|
115
|
+
But of course any of these requirements can also be fulfilled explicitly with self controlled steps **before** starting the
|
|
116
|
+
wxRuby3 installation procedure. See the platform specific sections of [Installing software requirements](INSTALL.md#installing-software-requirements) for details on
|
|
117
|
+
how to go about that.
|
|
118
|
+
|
|
119
|
+
[**1**] The wxRuby3 build process needs doxygen to generated XML files containing wxWidgets interface specs which are used to
|
|
120
|
+
generate interface definitions for SWIG
|
|
121
|
+
|
|
122
|
+
[**2**] The wxRuby3 build process uses SWIG to generate C++ source code for the wrapper interfaces from
|
|
123
|
+
which the native extensions are compiled. Both SWIG version 3 and version 4 are supported.
|
|
124
|
+
|
|
125
|
+
[**3**] The wxRuby3 build process uses these tools to adjust the shared library load paths ('rpath' setting) in case of embedded wxWidgets libraries.
|
|
126
|
+
|
|
127
|
+
### wxWidgets installation variants
|
|
128
|
+
|
|
129
|
+
wxRuby3 can be built and installed for 3 different types of wxWidgets installations:
|
|
130
|
+
|
|
131
|
+
1. A system installation of wxWidgets libraries and development files.<br>
|
|
132
|
+
This actually only has real meaning on Linux where this corresponds with installing distribution provided packages.
|
|
133
|
+
On MacOSX and Windows this only means that libraries are installed (as a user addon since no standard distribution
|
|
134
|
+
packages exist for these platforms but possibly using the administrator account) such that they can be loaded using
|
|
135
|
+
the default library load paths and the `wx-config` tool is executable from the default search path.<br>
|
|
136
|
+
This kind of installation is automatically detected and no special setup options are required for the wxRuby3 installation procedure.
|
|
137
|
+
2. A user installation of wxWidgets libraries and development files.<br>
|
|
138
|
+
This is the most likely scenario for a development setup of wxRuby3 where a special (possibly updated) release of
|
|
139
|
+
wxWidgets is installed to build wxRuby3 for.<br>
|
|
140
|
+
In this case the libraries and development files are most likely not found in standard locations and the wxRuby3
|
|
141
|
+
installation procedure will require specific options to have these locations provided.
|
|
142
|
+
3. An 'embedded' installation of wxWidgets setup by the wxRuby3 installation procedure.<br>
|
|
143
|
+
This is the default when using a standard binary package or when installing from source and the setup procedure does
|
|
144
|
+
not detect a (compatible!) system installation or if an option has been provided explicitly specifying to install an
|
|
145
|
+
embedded wxWidgets version.
|
|
146
|
+
|
|
147
|
+
Please note that in case of option **2** the user is responsible to make sure the wxWidgets shared libraries can be
|
|
148
|
+
found by the system's dynamic loader at runtime.
|
|
149
|
+
|
|
150
|
+
As described with option **3** a wxWidgets system installation must be compatible (>= version 3.2) to be selected for
|
|
151
|
+
source installation. In case the installed version does not meet this requirement it is ignored as if not installed.
|
|
152
|
+
|
|
153
|
+
For more information on how to install wxWidgets see the [Installing software requirements](INSTALL.md#installing-software-requirements) section below.
|
|
154
|
+
|
|
155
|
+
## wxRuby3 gem installation details
|
|
156
|
+
|
|
157
|
+
The wxRuby3 project provides a gem on [RubyGems](https://rubygems.org) which can be installed with the
|
|
31
158
|
standard `gem install` command line this:
|
|
32
159
|
|
|
33
160
|
```shell
|
|
34
161
|
gem install wxruby3
|
|
35
162
|
```
|
|
36
163
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
On Windows systems a prebuilt binary gem is available for the latest stable release(s) of [RubyInstaller](https://rubyinstaller.org)
|
|
40
|
-
installed rubies that will be installed by default if installing for that platform (including an embedded, latest
|
|
41
|
-
stable version, wxWidgets installation).<br>
|
|
42
|
-
Alternatively the source gem can be installed on Windows by installing with explicit platform specification like this:
|
|
164
|
+
Alternatively the gem can be downloaded from the [Github release assets](https://github.com/mcorino/wxRuby3/releases) and
|
|
165
|
+
stored locally. This local gem can than be installed like this:
|
|
43
166
|
|
|
44
167
|
```shell
|
|
45
|
-
gem install wxruby3
|
|
168
|
+
gem install /path/to/local/wxruby3.gem
|
|
46
169
|
```
|
|
47
170
|
|
|
48
|
-
|
|
171
|
+
This default installation command will allow the wxRuby3 installation process to scan available standard binary packages
|
|
172
|
+
([see here](#standard-packages)) for a match to the platform being installed on and install any matched package or revert
|
|
173
|
+
to a source install if none matched.<br>
|
|
174
|
+
This command will therefor succeed if:
|
|
175
|
+
- a matching binary package could be successfully downloaded and installed;
|
|
176
|
+
- the installation reverted to source install.
|
|
177
|
+
|
|
178
|
+
This command only fails when:
|
|
179
|
+
- a matching digest signature for the downloaded binary package could not be downloaded;
|
|
180
|
+
- the digest signature did not match the downloaded package contents.
|
|
181
|
+
|
|
182
|
+
> The result of successfully installing the gem on a Linux platform should be something like this:
|
|
183
|
+
> ```
|
|
184
|
+
> $ gem install wxruby3
|
|
185
|
+
> Building native extensions. This could take a while...
|
|
186
|
+
>
|
|
187
|
+
> The wxRuby3 Gem has been successfully installed including the 'wxruby' utility.
|
|
188
|
+
>
|
|
189
|
+
> In case no suitable binary release package was available for your platform you
|
|
190
|
+
> will need to run the post-install setup process by executing:
|
|
191
|
+
>
|
|
192
|
+
> $ wxruby setup
|
|
193
|
+
>
|
|
194
|
+
> To check whether wxRuby3 is ready to run or not you can at any time execute the
|
|
195
|
+
> following command:
|
|
196
|
+
>
|
|
197
|
+
> $ wxruby check
|
|
198
|
+
>
|
|
199
|
+
> Run 'wxruby check -h' for more information.
|
|
200
|
+
>
|
|
201
|
+
> When the wxRuby3 setup has been fully completed you can start using wxRuby3.
|
|
202
|
+
>
|
|
203
|
+
> You can run the regression tests to verify the installation by executing:
|
|
204
|
+
>
|
|
205
|
+
> $ wxruby test
|
|
206
|
+
>
|
|
207
|
+
> The wxRuby3 sample explorer can be run by executing:
|
|
208
|
+
>
|
|
209
|
+
> $ wxruby sampler
|
|
210
|
+
>
|
|
211
|
+
> Have fun using wxRuby3.
|
|
212
|
+
>
|
|
213
|
+
> Run 'wxruby -h' to see information on the available commands.
|
|
214
|
+
>
|
|
215
|
+
> Successfully installed wxruby3-0.9.8
|
|
216
|
+
> Parsing documentation for wxruby3-0.9.8
|
|
217
|
+
> Installing ri documentation for wxruby3-0.9.8
|
|
218
|
+
> Done installing documentation for wxruby3 after 2 seconds
|
|
219
|
+
> 1 gem installed
|
|
220
|
+
> ```
|
|
221
|
+
|
|
222
|
+
### Gem installation options
|
|
223
|
+
|
|
224
|
+
Two options are available to control the wxRuby3 gem installation process.
|
|
225
|
+
|
|
226
|
+
#### The `prebuilt` option
|
|
227
|
+
|
|
228
|
+
The `prebuilt=none|only` option can be used to either prevent binary package matching and installation (`prebuilt=none`)
|
|
229
|
+
or make binary package installation mandatory (`prebuilt=only`).
|
|
230
|
+
|
|
231
|
+
The following command therefor forces a wxRuby3 source installation and will never fail:
|
|
232
|
+
|
|
233
|
+
```shell
|
|
234
|
+
gem install wxruby3 -- prebuilt=none
|
|
235
|
+
```
|
|
49
236
|
|
|
50
|
-
|
|
237
|
+
And the following command will force binary package installation and fails if no matching package could be installed:
|
|
51
238
|
|
|
52
239
|
```shell
|
|
53
|
-
gem install wxruby3 --
|
|
240
|
+
gem install wxruby3 -- prebuilt=only
|
|
54
241
|
```
|
|
55
242
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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:
|
|
243
|
+
#### The `package` option
|
|
244
|
+
|
|
245
|
+
The `package=URL` option can be used to explicitly specify a binary package to install. This option implies `prebuilt=only`.
|
|
246
|
+
No package matching will be performed so mismatched binary packages will cause wxRuby3 to fail after installation.<br>
|
|
247
|
+
The `URL` can be specified as:
|
|
248
|
+
- an <b>absolute</b> local path like `/path/to/binary/package.pkg`
|
|
249
|
+
- an absolute `file://` URI like `file:///path/to/binary/package.pkg`
|
|
250
|
+
- an `http://` or `https://` URL
|
|
251
|
+
|
|
252
|
+
In all cases the associated `.sha` file <b>must</b> be located at the same path as the package file itself. If not the
|
|
253
|
+
installation will fail as well as when the signature does not match the digest of the package contents.
|
|
254
|
+
|
|
255
|
+
### Gem source setup
|
|
256
|
+
|
|
257
|
+
As said a gem-based source installation requires an additional command is to build the actual wxRuby3 extension libraries
|
|
258
|
+
for the platform installing on which is a wxRuby3 CLI command installed by the gem:
|
|
100
259
|
|
|
101
260
|
```shell
|
|
102
|
-
|
|
261
|
+
wxruby setup
|
|
103
262
|
```
|
|
104
263
|
|
|
105
|
-
|
|
106
|
-
|
|
264
|
+
The wxRuby3 CLI `wxruby` is installed by all wxRuby3 gems. In case of the source gem initially the CLI will provide only
|
|
265
|
+
the commands `wxruby setup` (to finish wxRuby3 extension installation) and `wxruby check`.
|
|
266
|
+
|
|
267
|
+
For most (user) installations the default setup command as shown above will suffice nicely. In this case the setup
|
|
268
|
+
(or installation) procedure will analyze the system to see if it meets the software requirements described above and if not
|
|
269
|
+
collect information on what is missing and needs to be added to finish the wxRuby3 installation. In order this would check:
|
|
270
|
+
|
|
271
|
+
- availability of the `doxygen` tool
|
|
272
|
+
- availability of the `swig` tool
|
|
273
|
+
- availability of the `git` tool
|
|
274
|
+
- availability of a (compatible) system installation of wxWidgets
|
|
275
|
+
- development tools and libraries required for an embedded wxWidgets installation (in case no system installation is used)
|
|
276
|
+
|
|
277
|
+
If any required software needs to be added the setup procedure will ask consent (showing what it intends to do) and, if given,
|
|
278
|
+
install the missing software using appropriate tooling for the platform (on Linux standard distribution installers which
|
|
279
|
+
may require a 'sudo' password and on MacOSX using either [MacPorts](https://www.macports.org/) or [Homebrew](https://brew.sh/)).
|
|
280
|
+
|
|
281
|
+
> Running the setup command will look something like this:
|
|
282
|
+
> ```
|
|
283
|
+
> $ wxruby setup
|
|
284
|
+
>
|
|
285
|
+
> ---
|
|
286
|
+
> Now running wxRuby3 post-install setup.
|
|
287
|
+
> This will (possibly) install required software, build the wxWidgets libraries,
|
|
288
|
+
> build the native wxRuby3 extensions and generate the wxRuby3 reference documentation.
|
|
289
|
+
> Please be patient as this may take quite a while depending on your system.
|
|
290
|
+
> ---
|
|
291
|
+
>
|
|
292
|
+
> [ --- ATTENTION! --- ]
|
|
293
|
+
> wxRuby3 requires some software packages to be installed before being able to continue building.
|
|
294
|
+
> If you like these can be automatically installed next (if you are building the source gem the
|
|
295
|
+
> software will be removed again after building finishes).
|
|
296
|
+
> Do you want to have the required software installed now? [yN] :
|
|
297
|
+
> ```
|
|
298
|
+
|
|
299
|
+
The initial message shown (between lines starting with '---' ) is indicative of what is going to happen depending
|
|
300
|
+
on options passed to the setup command.<br>
|
|
301
|
+
Building the wxRuby3 native extensions and generating reference documentation will always happen.
|
|
302
|
+
|
|
303
|
+
#### Disable prompting for automatic install
|
|
304
|
+
|
|
305
|
+
To prevent having the setup procedure asking consent the setup procedure can be started with the `--autoinstall` option
|
|
306
|
+
like this:
|
|
107
307
|
|
|
108
|
-
|
|
308
|
+
```shell
|
|
309
|
+
wxruby setup --autoinstall
|
|
310
|
+
```
|
|
109
311
|
|
|
110
|
-
|
|
312
|
+
Note that on Linux that may still present a prompt in case the `sudo` command requires a password.
|
|
111
313
|
|
|
112
|
-
|
|
314
|
+
#### Prevent automatic installation of software requirements
|
|
113
315
|
|
|
114
|
-
|
|
316
|
+
To prevent the setup procedure from considering to automatically install (with or without prompting) any missing software
|
|
317
|
+
requirements the setup procedure can be started with the `--no-autoinstall` option like this:
|
|
318
|
+
|
|
319
|
+
```shell
|
|
320
|
+
wxruby setup --no-autoinstall
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
The setup procedure will still analyze the system for available software requirements and if it finds any missing it
|
|
324
|
+
will end the procedure and show a message of what it found missing.
|
|
325
|
+
|
|
326
|
+
#### Force embedded wxWidgets installation
|
|
327
|
+
|
|
328
|
+
To prevent the setup procedure of using any system installed wxWidgets version the setup procedure can be started with
|
|
329
|
+
the `--with-wxwin` option like this:
|
|
330
|
+
|
|
331
|
+
```shell
|
|
332
|
+
wxruby setup --with-wxwin
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
This will force the setup procedure to build and install an embedded wxWidgets version for wxRuby3.
|
|
336
|
+
|
|
337
|
+
#### Setup with user installed wxWidgets
|
|
338
|
+
|
|
339
|
+
In case of a (custom) user installation of wxWidgets the `--wxwin` (and optionally `--wxxml`) option(s) can be used to
|
|
340
|
+
start the setup procedure to build for this installation like this:
|
|
341
|
+
|
|
342
|
+
```shell
|
|
343
|
+
wxruby setup --wxwin=/my/custom/wxWidgets
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
If the wxWidgets installation also holds the doxygen generated XML interface specification files in the default location
|
|
347
|
+
(`docs/doxygen/out/xml`) these will be used to build the wxRuby3 extensions. If not, the setup procedure will create these
|
|
348
|
+
files itself (from a freshly cloned copy of the wxWidgets repository).<br>
|
|
349
|
+
If the XML files have been created in a non-standard location that can be passed on to the setup procedure like this:
|
|
350
|
+
|
|
351
|
+
```shell
|
|
352
|
+
wxruby setup --wxwin=/my/custom/wxWidgets --wxxml=/my/alternate/wxWidgets/xml
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
> **NOTE**<br>
|
|
356
|
+
> Please be aware that in case of building wxRuby3 for a user installation of wxWidgets the user is also
|
|
357
|
+
> responsible for making sure the wxRuby3 extension library can find the wxWidgets libraries at runtime (normally this
|
|
358
|
+
> requires updating the standard shared library search path for the platform).
|
|
115
359
|
|
|
116
|
-
|
|
117
|
-
|
|
360
|
+
#### Setup with customized tool paths
|
|
361
|
+
|
|
362
|
+
If for whatever reason the required development tools `doxygen`, `swig` and/or `git` have been installed in a location
|
|
363
|
+
not in the standard executable search path the full path to these tools can be passed on the setup procedure using the
|
|
364
|
+
`--doxygen`, `--swig` and/or `--git` options like this:
|
|
118
365
|
|
|
119
366
|
```shell
|
|
120
|
-
wxruby --
|
|
367
|
+
wxruby setup --doxygen=/my/path/to/doxygen
|
|
121
368
|
```
|
|
122
369
|
|
|
370
|
+
#### Redirect log to customized path
|
|
371
|
+
|
|
372
|
+
The setup procedure will log full build results to a file setup.log at the location where the gem contents is stored.
|
|
373
|
+
If the setup fails the error message will display the log file location and by default if the setup succeeds the log
|
|
374
|
+
file is deleted.<br>
|
|
375
|
+
To redirect the log file to be stored at an alternate location an not be deleted in any case the `--log` option can be
|
|
376
|
+
used like this:
|
|
377
|
+
|
|
378
|
+
```shell
|
|
379
|
+
wxruby setup --log=/my/log/folder
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
In this case the log file would be created as `/my/log/folder/setup.log`.
|
|
383
|
+
|
|
384
|
+
## Installing software requirements
|
|
385
|
+
|
|
386
|
+
As described, instead of having the wxRuby3 setup procedure install the software requirements automatically these can
|
|
387
|
+
also be installed beforehand.
|
|
388
|
+
|
|
389
|
+
The following sections give some information how to accomplish that for the various supported platforms.
|
|
390
|
+
|
|
391
|
+
### Installing software requirements on Windows
|
|
392
|
+
|
|
393
|
+
On Windows these software requirements are only needed when **not** installing the binary gem.
|
|
394
|
+
|
|
395
|
+
#### Compiler
|
|
396
|
+
|
|
397
|
+
Download and install the [RubyInstaller MSYS2-Devkit](https://rubyinstaller.org/downloads/) which includes both Ruby
|
|
398
|
+
and a full set of development tools like GNU C++, make etc.
|
|
399
|
+
|
|
400
|
+
#### Doxygen
|
|
401
|
+
|
|
402
|
+
Download the Windows installer [here](https://doxygen.nl/download.html).
|
|
403
|
+
|
|
404
|
+
#### SWIG
|
|
405
|
+
|
|
406
|
+
Download the Windows archive [here](https://www.swig.org/download.html).
|
|
407
|
+
|
|
408
|
+
#### Git
|
|
409
|
+
|
|
410
|
+
Any Windows compatible Git version will do like [this](https://gitforwindows.org/) one.
|
|
411
|
+
|
|
412
|
+
#### wxWidgets
|
|
413
|
+
|
|
414
|
+
See the information on the wxWidgets website [here](https://wxwidgets.org/downloads/). Download and install either
|
|
415
|
+
a binary installation compatible with the MingW64 compiler version available from the RubyInstaller MSYS2-Devkit
|
|
416
|
+
installation (make sure to get this right or bad things will happen) or download a source package and build using the
|
|
417
|
+
compiler tools from the RubyInstaller MSYS2-Devkit installation. See [here](https://docs.wxwidgets.org/3.2/overview_install.html) for information about
|
|
418
|
+
building wxWidgets from source.
|
|
419
|
+
|
|
420
|
+
### Installing software requirements on MacOSX
|
|
421
|
+
|
|
422
|
+
#### Compiler
|
|
423
|
+
|
|
424
|
+
Install the XCode commandline tools using the command <code>sudo xcode-select --install</code>.
|
|
425
|
+
|
|
426
|
+
#### Doxygen
|
|
427
|
+
|
|
428
|
+
Depending on how you installed Ruby on your MacOS system use [Homebrew](https://brew.sh) with the command <code>brew install doxygen</code>
|
|
429
|
+
or use [MacPorts](https://www.macports.org/) with the command <code>port install doxygen</code>.
|
|
430
|
+
|
|
431
|
+
#### SWIG
|
|
432
|
+
|
|
433
|
+
Depending on how you installed Ruby on your MacOS system use [Homebrew](https://brew.sh) with the command <code>brew install swig</code>
|
|
434
|
+
or use [MacPorts](https://www.macports.org/) with the command <code>port install swig</code>.
|
|
435
|
+
|
|
436
|
+
#### Git
|
|
437
|
+
|
|
438
|
+
Is included in the XCode commandline tools.
|
|
439
|
+
|
|
440
|
+
#### wxWidgets
|
|
441
|
+
|
|
442
|
+
Either install a compatible wxWidgets version (>= 3.2) with the package manager of choice (Homebrew or MacPorts) if available
|
|
443
|
+
or download and build a source package from [here](https://wxwidgets.org/downloads/) (alternatively the wxWidgets Github
|
|
444
|
+
repository could be cloned). See [here](https://docs.wxwidgets.org/3.2/overview_install.html) for information about
|
|
445
|
+
building wxWidgets from source.
|
|
446
|
+
|
|
447
|
+
### Installing software requirements on Linux
|
|
448
|
+
|
|
449
|
+
#### Compiler
|
|
450
|
+
|
|
451
|
+
Install the GNU C++ compiler and common development tools like 'make' using the system provided package management.
|
|
452
|
+
|
|
453
|
+
#### Patchelf
|
|
454
|
+
|
|
455
|
+
Install the patchelf tool using the system provided package management.
|
|
456
|
+
|
|
457
|
+
#### Doxygen
|
|
458
|
+
|
|
459
|
+
Install the doxygen tool using the system provided package management.
|
|
460
|
+
|
|
461
|
+
#### SWIG
|
|
462
|
+
|
|
463
|
+
Install the swig tool using the system provided package management.
|
|
464
|
+
|
|
465
|
+
#### Git
|
|
466
|
+
|
|
467
|
+
Install the git tool using the system provided package management.
|
|
468
|
+
|
|
469
|
+
#### wxWidgets
|
|
470
|
+
|
|
471
|
+
Either install a compatible wxWidgets version (>= 3.2) with the system provided package management if available
|
|
472
|
+
or download and build a source package from [here](https://wxwidgets.org/downloads/) (alternatively the wxWidgets Github
|
|
473
|
+
repository could be cloned). See [here](https://docs.wxwidgets.org/3.2/overview_install.html) for information about
|
|
474
|
+
building wxWidgets from source.
|
|
475
|
+
|
|
123
476
|
## Building from source
|
|
124
477
|
|
|
125
478
|
Checkout the wxRuby3 sources from [GitHub](https://github.com/mcorino/wxRuby3) or download and unpack a release package.
|
|
@@ -127,16 +480,19 @@ Checkout the wxRuby3 sources from [GitHub](https://github.com/mcorino/wxRuby3) o
|
|
|
127
480
|
Requirements are the same as for installing the source gem. Gem dependencies are listed in the Gemfile in the root
|
|
128
481
|
of the wxRuby3 tree and should be installed by executing `bundle install`.<br>
|
|
129
482
|
To be able to generate HTML documentation the optional `:documentation` group should be included.<br>
|
|
130
|
-
To be able to run the Rake memory check task the
|
|
483
|
+
To be able to run the Rake memory check task the optional `:develop` group should be included.
|
|
131
484
|
|
|
132
485
|
The wxRuby3 project provides a Rake based build system. Call `rake help` to get an overview of the available commands.
|
|
133
486
|
As mentioned there the `rake configure` command is required as the very first command. Call `rake configure[--help]` to
|
|
134
487
|
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
|
|
488
|
+
As with the source gem 3 options exist for the wxWidgets installation for which details can be specified to `rake configure`.
|
|
136
489
|
|
|
137
490
|
When wxRuby3 has been configured the extensions can be build by calling the `rake build` command. The wxRuby3 build
|
|
138
491
|
commands are executed using parallel task execution by default.
|
|
139
492
|
|
|
140
493
|
When the build has finished without errors the regression tests can be run by calling `rake test`.
|
|
141
494
|
|
|
495
|
+
After successfully building the wxRuby3 extension libraries (and possibly embedded wxWidgets libraries) a binary package
|
|
496
|
+
can be created by call `rake binpkg`.
|
|
497
|
+
|
|
142
498
|
For more details concerning the wxRuby3 development strategy and build options see [here](TODO).
|