====== 'MSYS2' / 'MinGW' Notes ======

The ''MSYS2'' / ''MinGW'' project is now hosted at

  * [[https://www.msys2.org/wiki/MSYS2-installation/]]


\\
===== Downloading the 'MSYS2' Installer =====

An installer for a package that **//runs//** on 64 bit Windows only but can also **//build//** executables for 32 bit Windows can be downloaded at

  * [[https://repo.msys2.org/distrib/x86_64/]]

Download file [[https://repo.msys2.org/distrib/x86_64/msys2-x86_64-20221216.exe|msys2-x86_64-20221216.exe]] or newer.


\\
:!: Development of an MSYS2/MinGW package that **//runs//** on 32 bit Windows has been discontinued, but earlier packages
(e.g. for 32 bit Windows 7) are still available at

  * [[https://repo.msys2.org/distrib/i686/]]

Download file [[https://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe|msys2-i686-20200517.exe]], which is the latest version.

\\
===== Running the Downloaded Installer =====

Open a console window, change to the download directory, and run the downloaded ''.exe'' file to install the base packet.
The installer adds some new entries to the Windows start menu, and you have to click on one of those to open a command line window
with the preferred build environment settings. See next chapter.


\\
===== Opening a Shell in a Selected Build Environment =====

Klick on the menu entry for the preferred build environment to open an associated console Window.

The default environment for fresh installations is **''MSYS2 MinGW UCRT x64''**, which uses a "Universal Runtime" library that
is also used by current Visual Studio build environment versions, and shipped with Windows 10 and later, but is only available
for 64 bit Windows versions.

The **''MSYS2 MinGW 32-bit''** and **''MSYS2 MinGW 64-bit''** environments use the older MSVC runtime library which is also available
and shipped with older 32 bit and 64 bit Windows versions.

There are also some other MSYS2 build environments, and a description of the different environments can be found here:

  * **MSYS2 Environments**\\
    https://www.msys2.org/docs/environments/


\\
===== Upgrading the Installation =====

The MSYS2 system uses the **''pacman''** program to maintain installed packages.
 
In current installations, it should be sufficient to run

<codedoc code>
pacman -Syuu
</codedoc>

within any of the MSYS2 shells (maybe multiple times after each other) to upgrade all components
to the latest versions.

:!: **Note for Windows 7**: in an installation on Windows 7 32 bit the command updated some basic programs, then asked to 
close the MSYS2 shell and re-open it before continuing by repeating the command. However, it was impossible
to re-open a new shell until the machine had been rebooted. So the older way described below for older versions
may be generally preferred.


\\
In **//older installations//**, updates may need to be run in 2 steps:

First update programs that may be in use:

<codedoc code>
pacman ~~codedoc:clean:--~~needed -S bash pacman pacman-mirrors msys2-runtime
</codedoc>

If any packages have been updated, you have to close and re-run the MSYS2 shell before continuing.

Then run 

<codedoc code>
pacman -Syu
</codedoc>

to update the remaining packages.


\\
===== Installing Additional Packages ======

The command

<codedoc code>
pacman -Ss ~~codedoc:<em>search-term</em>~~
</codedoc>

can be used to search for packages that are available for installation and have ''search-term'' in their name or description.


\\
==== Installing Development Tools ====

There are different **toolchains** available which can be used to build 32 bit or 64 bit binaries
for Windows, using different runtime libraries.

The //**U**niversal **C** **R**un**T**ime for **64** Bit// library is only available for and pre-installed on
64 bit versions of Windows 10 and newer.

Binaries for 32 bit Windows versions or versions before Windows 10 should be built using the legacy
Windows runtime.

<code>
pacman -S --needed mingw-w64-i686-toolchain           # 32 bit binaries (gcc and legacy runtime)
pacman -S --needed mingw-w64-x86_64-toolchain         # 64 bit binaries (gcc and legacy runtime)

pacman -S --needed mingw-w64-ucrt-x86_64-toolchain    # 64 bit binaries (gcc and UCRT runtime)

pacman -S --needed mingw-w64-clang-i686-toolchain     # 32 bit binaries (clang)
pacman -S --needed mingw-w64-clang-x86_64-toolchain   # 64 bit binaries (clang)

pacman -S --needed mingw-w64-clang-aarch64-toolchain  # 64 bit binaries for ARM64 (clang)

pacman -S --needed base-devel                         # Some basic development tools
</code>


\\
**meld**, the excellent graphical diff and merge tool:

<code>
pacman -S --needed mingw-w64-i686-meld3    # The 32 bit version.
pacman -S --needed mingw-w64-x86_64-meld3  # The 64 bit version.
</code>


\\
git & gitk:

<code>
pacman -S --needed git
</code>

This package may be required only if the graphical tool ''gitk'' fails to start:

<code>
pacman -S --needed mingw-w64-i686-tk    # The 32 bit version.
pacman -S --needed mingw-w64-x86_64-tk  # The 64 bit version.
</code>


If you want to use ''git'' to not only clone remote repos, you may want to do some 
[[:miscellaneous_tips:20_software_development:git_notes:git_configuration|basic git configuration]]
that greatly simplifies working with ''git''.



\\
===== Git Configuration ======

**''Git for Windows''** is a different package based on MSYS2/MinGW, but uses a different configuration for the shell and for git.

To avoid problems when working with a MinGW32 or MinGW64 shell in a directory containing a git repo cloned (or maintained) by ''Git for Windows'',
some configuration files should be copied from the ''Git for Windows'' installation directory (e.g. ''/c/opt/git/'')
to the Msys installation directory (e.g. ''/c/opt/msys32/''), namely:

  * ''/etc/gitconfig''
  * ''/etc/gitattibutes''
  * ''/etc/profile.d/git-prompt.sh''

Among other things, this avoids that different line endings are assumed by the different git installations in ''Git for Windows''
and MSYS2/MinGW.


\\
===== Invalid or Missing Package PGP/GPG Keys =====

If an error occurs because a PGP key is missing or has expired, the hints in this paragraph may
help to fix the problem.

:!: Note: In the examples below, a WKD key server is explicitly specified because 
older installations may use the obsolete pool.

\\
If a PGP key is missing or has expired, run the following command to refresh all keys:

<codedoc code>
pacman-key ~~codedoc:clean:--~~keyserver hkp://keyserver.ubuntu.com:80 ~~codedoc:clean:--~~refresh-keys
</codedoc>

It's possible that the command above has to be run several times to fetch all required keys.


\\
If a key is still missing or can't be updated automatically, import the key manually: 

<codedoc code>
pacman-key ~~codedoc:clean:--~~keyserver hkp://keyserver.ubuntu.com:80 -r ~~codedoc:<em>5F944B027F7FE2091985AA2EFA11531AA0AA7F57</em>~~
</codedoc>


\\
Then edit the key to increase the trust level. Run

<codedoc code>
pacman-key ~~codedoc:clean:--~~edit-key ~~codedoc:<em>5F944B027F7FE2091985AA2EFA11531AA0AA7F57</em>~~
</codedoc>

then enter ''trust'', select level 4 (full), and enter ''save'' to save the changes.

:!: Note: in an installation on Windows 7 32 bit level 4 was not saved. The increased trust level was only saved when level '5' (ultimate) was selected.
Car must also be taken that the appropriate key for 'y' is pressed (in German, 'j') to accept the level.


\\
Then repeat the command from the basic installation

<codedoc code>
pacman -Syu
</codedoc>


----

 --- //Martin Burnicki [[martin.burnicki@burnicki.net]], last updated 2023-11-06//