Windows build instructions documentation.

[ioquatix]

cc @larskanis @MSP-Greg

[larskanis]

Very nice!

I think these instructions should also be linked with building_ruby.md and with the instructions reg. Visual C. I stumbled upon them only accidentally, so at best we link forth and back.

The topic about icons applies on Mingw as well.

[MSP-Greg]

LGTM. Wonder if any mention should be made about dependencies, both mingw & mswin.

mswin is using libffi libyaml openssl readline-win32 zlib. I think readline-win32 is just for C, reline would be used.

Should https://github.com/Microsoft/vcpkg be mentioned as a 'recommended source' for packages with mswin builds?

Not sure about doc locations, as mswin is referred to in win32/README.win32? Or, combine mingw & mswin in one doc?

[larskanis]

IMHO win32/README.win32 should contain a link only, pointing to doc/windows.md and that file should contain both environments.

[hsbt]

I have same concern as @MSP-Greg. This instruction is only mingw platform, not mswin. We should mention about it.

[mohits]

Thanks @ioquatix - I tried the cmd instructions on a Windows 10 PC where I have never built Ruby for Windows before. Just two notes:
[1] It works! Takes a while (50min on my PC to do the final building, but yes, it works)
[2] It worked in my RubyInstaller2 setup for Ruby 3.1 and not for Ruby 3.0

I wonder if it's useful also to note that in the guide.

At the end of 40min, I was able to do:

$ ruby -v
ruby 3.2.0dev (2022-12-19T15:44:23Z master b2f53dccbe) [x64-mingw-ucrt]

[MSP-Greg]

@mohits

[2] It worked in my RubyInstaller2 setup for Ruby 3.1 and not for Ruby 3.0

Ruby 3.0 is built with mingw gcc, Ruby 3.1 is built with ucrt gcc, so if one does ridk enable ucrt64 with Ruby 3.0, one is enabling a gcc that isn't installed. Do your recall what the issue was when you used Ruby 3.0?

JFYI, if you have more than one CPU core, you can use make -j<# of cores>, which will often speed up the process.

[mohits]

Hi @MSP-Greg... Exactly that - no compilers found.

I expected that was the case when I saw the error, but wanted to highlight that we should add a note about the environment being set by the command and that it would work with Ruby 3.1 or newer (and/or include the older variant, if relevant).

Thanks for the tip on the cores... should add that in also, I feel.

I tried to build it as a relative newbie keen to see how it works, and wanted to report my observations 🙂

[MSP-Greg]

@mohits Thanks for the info, and thanks for testing it.

I'm not sure how best to proceed.

1. Do we suggest using a RubyInstaller2 build with 'devkit', or a stand-alone MSYS2 install? Stand-alone means a user only has one 'MSYS2' install to update. Note that one MSYS2 install can have both mingw & ucrt toolchains and packages. But, there may be occasional compatibility issues with older Ruby builds. There is also the issue of major version package changes, as will happen when MSYS2 changes from OpenSSL 1.1.1 to OpenSSL 3.0.x.

2. Do we assume knowledge of Git, which is very helpful when using Microsoft/vcpkg for mswin builds?

3. Should the doc's detail the differences between building from a Ruby 'tarball' and building from the Git repo?

4. Should the doc's mention the differences between 'pre-assembled' builds (like RubyInstaller2 & ruby-loco) and builds done locally?

This discussion has been framed regarding master, but a user could certainly follow similar steps to try a backport in an older version of Ruby.

Finally, I'm like to contribute, but I've been too close to it for too long to know how much detail to include...

[mohits]

Hi @MSP-Greg - thanks.

In my opinion, the Building Ruby document does not need to cover everything but should offer at least 1 path that will almost certainly work for most people trying it the first time and/ or highlight what might go wrong. On my blog, most of my starter-style posts are written to work that way and to also include things that go wrong (and why).

Briefly, in response to your comments:

1. See the idea below.
2. Yes, we can assume Git is roughly understood - the current document links to git for windows and provides the git clone command that works assuming git for windows is installed. So, nothing more needed at that level, I feel.
3. If we scope the post to cover building from the git repo, I think that's good enough. That said, I imagine building from the tarball is almost exactly the same, other than the git clone command. I can try that out later to see what should be added.
4. If the user has already come to the page for 'Building Ruby' instead of 'Installing Ruby', I think we are fine with the instructions not focusing on pre-assembled builds. That discussion is in the scope of a separate page some place, in my opinion. However, the one thing that I think makes sense is to include something along the lines of How do I use a Ruby I built myself? - again, a one-liner on this page would be great but may still be optional.

I followed the same ideas when I wrote these pages for JRuby:

• Building from source - https://notepad.onghu.com/2021/jruby-win-day3-building/
• Using locally built JRuby JARs - https://notepad.onghu.com/2021/jruby-use-new-jruby-jars/

Based on this, I would recommend we probably add:

• A line that says "In the instructions below, we assume that you are using RubyInstaller 2 + DevKit for Ruby 3.1 or newer" since this gives us the at least 1 path that has a very high chance of working
• Probably a note that says "in this guide, we will get the latest code from the master branch of Ruby's GitHub"
• Any other relevant reference for building from tarball / other environments [this is optional]
• A comment on where the artefacts are generated and to at least run ruby.exe and see the current version that you just built (gratification)

I also personally feel that documentation PRs should be fast-tracked if they are not dangerous since they usually add value. On that idea, we should wait just a couple of days more and accept enhancements as people (like me) find things that can be improved.

You're doing enough :) so feel free to let us ferret around and suggest things that make sense for others :)

It's my working day now, so I will try to get to this later.

[mohits]

One more thing - I think this does not consider building YJIT since that needs Rust... so, that gets skipped.

[MSP-Greg]

@mohits

LGTM.

The current code essentially only builds ruby core. Also, I'm not sure if Windows builds support YJIT. All config summaries show:

   * MJIT support:        no
   * YJIT support:        no

Also, I tried it locally, and I needed to change to the following (PowerShell script):

sh autogen.sh
$config_args = "--build=$env:MINGW_CHOST --host=$env:MINGW_CHOST --target=$env:MINGW_CHOST"
sh -c "./configure -C --disable-install-doc $config_args"
make -j<parallel qty>

[ioquatix]

This document is by no means perfect, but it's a good step in the right direction. Please feel free to create more PRs to improve it. I would love to see everyone who gave feedback update the document. Let's make it easier for people to develop Ruby on Windows.