Add mingw documentation

[dg0yt]

This PR adds basic documentation for using vcpkg with mingw.

The instructions weren't tested line by line from scratch. But they are based on recent work with vcpkg.

[dg0yt]

What I would like to add later is comments about the "system binaries" configuration, affecting cmake and ninja. But this really needs to be tested before published. This can be done i another PR.

[dg0yt]

Ready, from my POV.

[longnguyen2004]

Thanks for the PR! I really appreciate having proper documentation for mingw.
I think we should add a note that users should use a Mingw-w64 based toolchain, not the old MinGW based toolchain. There was a discussion about this in #14561, and an actual issue #16647. Basically put, practically everyone assumes we're using a Mingw-w64 based toolchain, so we should make that clear as well.

[NancyLi1013]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[dg0yt]

I think we should add a note that users should use a Mingw-w64 based toolchain, not the old MinGW based toolchain. There was a discussion about this in #14561, and an actual issue #16647. Basically put, practically everyone assumes we're using a Mingw-w64 based toolchain, so we should make that clear as well.

I was inclined to answer again with "know your toolchain" but maybe this needs more attention indeed. I looked through the mingw mailing lists, and it confirms the MinGW project's mood as reported in #14561, in particular when users of mingw-w64 raise questions there.

To make it really clear, I would replace MinGW with Mingw-w64 in most occurences. This is not meant to exclude MinGW if someone is willing to support that in terms of documentation, triplets and or ports. But I don't think MinGW is ready for usage with vcpkg at this stage.

In particular, I won't change the mingw.md file name. However, renaming the community triplets should be seriously considered. And last not least it is scripts/toolchains/mingw.cmake which selects mingw-w64 tools by ${CMAKE_SYSTEM_PROCESSOR}-w64-mingw32- prefixes (note the w64).

[longnguyen2004]

But I don't think MinGW is ready for usage with vcpkg at this stage.

It's not about vcpkg, it's about upstream expectation. Pretty much every libraries out there expect Mingw-w64, not MinGW.
I would be happy to add a check for it in mingw.cmake, if there's a way to differentiate between them purely by compiler output.

[dg0yt]

But I don't think MinGW is ready for usage with vcpkg at this stage.

It's not about vcpkg, it's about upstream expectation. Pretty much every libraries out there expect Mingw-w64, not MinGW.

IMO there is nothing wrong with upstream. It is downstream, i.e. vcpkg users, which expect the ports to magically work with MinGW when vcpkg talks about MinGW. But when there is no x86_64 in MinGW, it won't come through vcpkg.

I would be happy to add a check for it in mingw.cmake, if there's a way to differentiate between them purely by compiler output.

I didn't try any MinGW toolchain in the last years, and the currently broken MinGW website doesn't help. But I don't think they use the same prefix, or report the same autoconf triplet, as mingw-w64. I assume i386-pc-mingw32 or similar for MinGW. And for compiler output, for mingw-w64 targeting x64, I can run:

$ x86_64-w64-mingw32-gcc -dumpmachine
x86_64-w64-mingw32

So I would look for -w64-mingw32.

[dg0yt]

And now I realize that vcpkg passes the MinGW autotools triplets (...-pc-mingw32) to configure. IMO it should use the ...mingw-w64-w64-mingw32 autotools triplets when it targets Mingw-w64.

[longnguyen2004]

And now I realize that vcpkg passes the MinGW autotools triplets (...-pc-mingw32) to configure. IMO it should use the ...mingw-w64-w64-mingw32 autotools triplets when it targets Mingw-w64.

To be honest, letting autotools decide what triplet to use is a bit unreliable, and I would really like for each triplet to specify its corresponding autotools triplet, but that would require some work on vcpkg_configure_make. @Neumann-A What do you think?

[dg0yt]

letting autotools decide what triplet to use is a bit unreliable

I didn't want to suggest that autotools should decide. I just want to make a distinction from vcpkg's triplets.

I would really like for each triplet to specify its corresponding autotools triplet

In the vcpkg triplet file, at least optionally? Well, this is also what I think. It would facilitate adding new or customizing existing triplets (Android, mingw-w64 ucrt). The triplet files are in the hand of the users.

that would require some work on vcpkg_configure_make

I got the impression that there is already a backlog of open PRs for this script, and I noticed some issues which aren't reported yet.

[longnguyen2004]

I didn't want to suggest that autotools should decide. I just want to make a distinction from vcpkg's triplets.

Oh alright, I thought you were talking about the MinGW vs. Mingw-w64 issue and how the *-pc-mingw32 triplet is related to it.

[dg0yt]

I added another section how to to avoid mixing MSYS binaries from different installations.

Background:
When building port libpq from MSYS2 bash, I ran into strange issues. The root cause is a mix of differents MSYS2 installations which is cause argument passing/quoting/escaping to fail. I found that this is discouraged by the MSYS2 project.

Note: IMO the underlying problem might effect even building ports for MSVC targets.

For the record, my intermediate goal is to build the gdal. At the moment I have to add 10 PRs to vcpkg HEAD, and the next one is coming.

[dg0yt]

I had to extend the PATH recommendation to also exclude /bin. (My test installation were not fully consistent before this change.)

I think that it might make sense to handle this PATH quirk in the triplet files and/or other central files. But this is out of scope for this documentation PR.

Removing the local msys2 installation from PATH means that even simple tools like touch are not available without vcpkg_acquire_msys / before vcpkg_configure_make. But it doesn't look like multiple calls to vcpkg_acquire_msys are a good thing: They result in multiple msys roots. In some cases, such as a call to touch in the non-Windows path of port gdal, this can be solved by using the portable commands of cmake -E.

This basically marks the point where I consider this PR done: It is tested on multiple installation of Windows. (Yes, I succeeded in building gdal with mingw on Windows. It is as broken as on Linux, #9068).

[ras0219-msft]

LGTM, thanks for making this awesome doc @dg0yt !