You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+61-18Lines changed: 61 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,42 +2,85 @@
2
2
3
3
Cross platform action for Ruby CI that configures build tools and installs packages needed for compiling.
4
4
5
-
The action's input are shown below:
5
+
The action's inputs are shown below:
6
6
7
7
```yaml
8
8
- uses: MSP-Greg/setup-ruby-pkgs@v1
9
9
with:
10
10
ruby-version:
11
-
apt: # Ubuntu
12
-
brew: # macOS
13
-
mingw: # Windows mingw
14
-
msys2: # mingw
15
-
mswin: # Windows mswin
16
-
choco: # mswin
17
-
vcpkg: # mswin
11
+
apt: # Ubuntu
12
+
brew: # macOS
13
+
mingw: # Windows mingw / mswin
14
+
msys2: # mingw
15
+
mswin: # Windows mswin
16
+
choco: # mswin
17
+
vcpkg: # mswin
18
18
```
19
19
20
-
### Input Information
20
+
## Input Information
21
21
22
-
All inputs are optional. If ruby-versions is used, the code for [ruby/setup-ruby](https://github.com/ruby/setup-ruby) is used.
22
+
All inputs are optional.
23
23
24
-
#### apt (Ubuntu)
24
+
### ruby-version:
25
+
26
+
Installs the Ruby version using the code from [ruby/setup-ruby](https://github.com/ruby/setup-ruby). The available versions can be found in its [README](https://github.com/ruby/setup-ruby/blob/master/README.md#supported-versions).
27
+
28
+
### apt: (Ubuntu)
25
29
26
30
List of packages to install. Space delimited. Special options are `_update_` and `_upgrade_`.
27
31
28
-
#### brew (macOS)
32
+
### brew: (macOS)
29
33
30
34
List of packages to install. Space delimited. Special options are `_update_` and `_upgrade_`.
31
35
36
+
### mingw: (Windows)
37
+
38
+
<dl>
39
+
<dt><b>Ruby 2.4 & later</b></dt>
40
+
<dd>List of MSYS2 MinGW packages to install.
41
+
Space delimited. The package prefix (<code>mingw-w64-x86_64-</code>) is not required.<br/>If <code>_upgrade_</code> is included in the input, all packages needed by the gcc tools are updated.<br/>If <code>openssl</code> is included, an appropriate package will be installed.
42
+
</dd>
43
+
<dt><b>Ruby 2.3 & earlier</b></dt>
44
+
<dd>The following DevKit packages are available:
45
+
<ul>
46
+
<li>libffi-3.2.1</li>
47
+
<li>openssl-1.0.2j</li>
48
+
<li>ragel-6.7</li>
49
+
<li>sqlite-3.7.15.2 (sqlite3)</li>
50
+
<li>zlib-1.2.8</li>
51
+
</ul>
52
+
</dd>
53
+
<dt><b>Ruby mswin</b></dt>
54
+
<dd>If <code>openssl</code> is included, it will be installed for mswin as a convenience.<br/>Likewise, if <code>ragel</code> is included, the MSYS2 ragel package will be installed.
55
+
</dl>
56
+
57
+
### msys2: (Windows)
58
+
59
+
<dl>
60
+
<dt><b>Ruby 2.4 & later</b></dt>
61
+
<dd>List of MSYS2 packages to install. Space delimited. These are command line utilities, and are rarely needed.
62
+
</dd>
63
+
<dt><b>Ruby 2.3 & earlier</b></dt>
64
+
<dd>No action, as no utilities are available for the older MSYS/DevKit.</dd>
65
+
</dl>
32
66
33
-
#### mingw (Windows)
67
+
### mswin: (Windows)
34
68
35
-
List of MSYS2 MinGW packages to install. Space delimited. The package prefix (`mingw-w64-x86_64-`) is not required. At present, only 64 bit Rubies and MSYS2 are available.
69
+
Installs MSYS2 packages. These are typically build utilities, such as bison, ragel, etc. As in pacman, MinGW packages must be prefixed with `mingw-w64-x86_64-`.
36
70
37
-
An input string of `_upgrade_` can be included, and will update all packages needed by the gcc tools.
71
+
### choco: (Windows)
72
+
73
+
List of packages to install. Space delimited. Most packages are compiled with msvc, so normally used with mswin builds.
74
+
75
+
### vcpkg: (Windows)
76
+
77
+
List of packages to install. Space delimited. All packages are compiled with msvc, so normally used with mswin builds. An environment variable `OPT_DIR` is set to
This document is intended to provide information on Windows Ruby builds that may help with Windows CI problems.
7
+
8
+
Problems are most likely to occur with gems/repos that require compiling. They may also occur when installing dependencies that require compiling.
9
+
10
+
Much of the below information is general, and may also help with users having problems locally.
11
+
12
+
## A few specifics
13
+
14
+
Unlike Ubuntu and macOS, standard Windows does not have native compiling tools, nor does it have package libraries.
15
+
16
+
* Because of this, Windows Rubies are self-contained. All non-system runtime dlls are packaged with each build, but their lib and header files are not included.
17
+
18
+
For example, if one has both Ruby 2.4 and Ruby 2.7 installed, 2.4 will use its bundled OpenSSL 1.0.2 dlls, and 2.7 will use its bundled OpenSSL 1.1.1 dlls. Both can be running at the same time.
19
+
20
+
* Standard Windows Rubies (`RUBY_PLATFORM.include? 'mingw'` is true) are built with either MSYS or [MSYS2](https://github.com/msys2) build tools and packages, and are often referred to as 'mingw' builds. These are available in both 32 and 64 bit builds, but only 64 bit builds are available on GitHub Actions.
21
+
22
+
* Ruby mswin builds (`RUBY_PLATFORM.include? 'mswin'` is true) are built with the Microsoft Visual C tools. The [ruby/ruby](https://github.com/ruby/ruby) repo runs CI on mswin builds, and several of the stdlib repos do the same.
23
+
24
+
* Ruby MinGW builds and mswin builds use different versions of Microsoft Visual C. MinGW builds have a dependency on `msvcrt.dll`, while mswin builds have a dependency on `vcruntime140.dll`. Because of this, the compiled code is not compatible.
25
+
26
+
* All builds from 2.4 and later use a Windows specific mechanism for finding dll's (known simply as 'manifest'). The dlls are located in `bin/ruby_builtin_dlls`. The manifest places them first in the 'lookup resolution'. Hence, testing against a specific dll version requires adjustments.
27
+
28
+
## MinGW builds - general info
29
+
30
+
What is DevKit? You may have seen `-rdevkit` or `require 'devkit'` in scripts for Windows Ruby CI. The term 'devkit' is also used to refer to the collection of build tools used to compile both MinGW Ruby and extension gems. So, one might see the phrase 'have you installed devkit?'. As above, the file that 'activates' the devkit thru ENV settings is named `devkit.rb`.
31
+
32
+
### Ruby 2.4 & later
33
+
34
+
Compiled with a set of gcc tools that are part of [MSYS2]. [MSYS2] is independent of Ruby and includes four general categories: a set of bash tools (tar, sed, grep, etc), a set of compiler tools (gcc, llvm, cmake, etc), a set of library packages (libffi, openssl, zlib, etc), and applications/languages (git, perl, python, imagemagick, inkscape, etc).
35
+
36
+
### Ruby 2.3 & earlier
37
+
38
+
Compiled with a set of gcc tools known as MSYS. MSYS is no longer supported and a limited number of packages are available. The MSYS build tools 'devkit' was packaged by the group that built the Rubies.
39
+
40
+
### Build Tool Activation
41
+
42
+
[ruby/setup-ruby] adds all `ENV` information required to use the correct set of build tools. Most of the below information is general background that pertains to local use.
43
+
44
+
* MinGW Rubies include a file named `devkit.rb`. Requiring it adds the build tools' locations to Path. For CI, the locations are added by [ruby/setup-ruby](https://github.com/ruby/setup-ruby).
45
+
46
+
* MinGW Rubies also include a file `rubygems/defaults/operating_system.rb`, which essentially performs the same function as `devkit.rb`. When a gem needs to be compiled, it adds the builds tools to `ENV`. It also adds the locations of the devkit package dlls to the dll library 'lookup resolution' chain. This is done with a Windows specific system call.
47
+
48
+
* The MSYS build tools used in older MinGW Rubies was a proprietary package. The code to generate `devkit.rb` was contained in it, and the location of the tools was hard coded by the install.
49
+
50
+
* In newer MinGW Rubies, `devkit.rb` and `operating_system.rb` are included in the Ruby build and use vendored code to determine the [MSYS2] location. One can install [MSYS2] independent of Ruby and `devkit.rb` and `operating_system.rb` will still find it.
51
+
52
+
53
+
## MinGW builds - gcc compatibility
54
+
55
+
Many Windows CI providers only have the most recent Ruby patch/teeny versions installed. With GitHub Actions and [ruby/setup-ruby](https://github.com/ruby/setup-ruby), all Windows versions from Ruby 2.4 and later are available. There may be compatibility issues when using a current MSYS2 gcc with older Ruby patch versions.
56
+
57
+
| gcc \\ ruby | 2.4 | 2.5 | 2.6 | 2.7 |
58
+
| :---: | :--- | :--- | :--- | :--- |
59
+
|**6.3.0-3**| 2.4.1 ||||
60
+
|**7.2.0-2**|| 2.5.0 |||
61
+
|**8.2.1-1**||| 2.6.0 ||
62
+
|**8.3.0-2**| 2.4.6 | 2.5.5 | 2.6.3 ||
63
+
|**9.2.0-1**| 2.4.7 | 2.5.6 | 2.6.4 ||
64
+
|**9.2.0-2**| 2.4.9 | 2.5.7 | 2.6.5 | 2.7.0 |
65
+
66
+
67
+
## Windows OpenSSL
68
+
69
+
The following lists the OpenSSL versions used for the most recent release:
70
+
71
+
| Ruby | OpenSSL | Compiler |
72
+
| :---: | :---: | :---: |
73
+
|**2.2**| 1.0.2j | MSYS gcc |
74
+
|**2.3**| 1.0.2j | MSYS gcc |
75
+
|**2.4**| 1.0.2t | MSYS2 gcc |
76
+
|**2.5**| 1.1.1*| MSYS2 gcc |
77
+
|**2.6**| 1.1.1*| MSYS2 gcc |
78
+
|**2.7**| 1.1.1*| MSYS2 gcc |
79
+
|**mingw**| 1.1.1*| MSYS2 gcc |
80
+
|**mswin**| 1.1.1*| msvc |
81
+
82
+
On the mswin platform, `openssl` can used in either the `mingw:` input or the `choco:` input, both will install an msvc OpenSSL build.
83
+
84
+
When `openssl` is included, the correct OpenSSL version (based on the Ruby version and platform) will be installed. For the mswin platform, the environment variable `SSL_DIR` is set to the following, which is the location of the msvc OpenSSL package:
0 commit comments