Setup MSYS2

setup-msys2 is a JavaScript GitHub Action (GHA) to setup an MSYS2 environment (i.e. MSYS, MINGW32, MINGW64, UCRT64, CLANG32, and/or CLANG64 shells) using the GHA toolkit for automatic caching.

Context

MSYS2 is available by default on the windows-latest virtual environment for GitHub Actions, located at C:\msys64. However, there are some caveats with using the default installation as-is:

It is updated every ~10 days.
Caching of installation packages is not supported.
MSYS2/MINGW are neither added to the PATH nor available as a custom shell option.
On versions older than windows-2022, it includes a non-negligible set of pre-installed packages. As a result, update time can be up to 10 min (see actions/virtual-environments#1572).

setup-msys2 works around those constraints:

Using option release: false, the default installation is used, but automatic caching is supported and a custom entrypoint is provided.
By default (release: true), setup-msys2 downloads and extracts the latest tarball available at repo.msys2.org/distrib/x86_64, a clean and up-to-date environment is set up in a temporary location, and a custom entrypoint (msys2) is provided. Hence, the overhead of updating pre-installed but unnecessary packages is avoided.

Therefore, usage of this Action is recommended to all MSYS2 users of GitHub Actions, since caching and the custom entrypoint are provided regardless of option release.

NOTE: in the future, bash might default to MSYS2 (see actions/virtual-environments#1525).

Usage

  - uses: msys2/setup-msys2@v2

Then, for scripts:

  - shell: msys2 {0}
    run: |
      uname -a

It is also possible to execute specific commands from cmd/powershell scripts/snippets. In order to do so, -c is required:

  - shell: powershell
    run: msys2 -c 'uname -a'

  - shell: cmd
    run: msys2 -c 'uname -a'

Default shell

In order to reduce verbosity, it is possible to set msys2 as the default shell. For example:

  defaults:
    run:
      shell: msys2 {0}
  steps:
  - uses: msys2/setup-msys2@v2
    with:
      update: true
      install: >-
        base-devel
        git
  #- run: git config --global core.autocrlf input
  #  shell: bash
  - uses: actions/checkout@v2
  - run: git describe --dirty

Note that setting autocrlf is required in specific use cases only. See actions/checkout#250.

Build matrix

It is common to test some package/tool on multiple environments, which typically requires installing different sets of packages through option install. GitHub Actions' strategy and matrix fields allow to do so, as explained in docs.github.com: Configuring a build matrix and docs.github.com: jobs.<job_id>.strategy.matrix. See, for instance:

  strategy:
    matrix:
      include:
        - { sys: mingw64, env: x86_64 }
        - { sys: mingw32, env: i686 }
        - { sys: ucrt64,  env: ucrt-x86_64 }  # Experimental!
        - { sys: clang64, env: clang-x86_64 } # Experimental!
  steps:
    - uses: msys2/setup-msys2@v2
      with:
        msystem: ${{matrix.sys}}
        install: mingw-w64-${{matrix.env}}-openssl

Alternatively, option pacboy allows using a single matrix variable:

  strategy:
    matrix:
      sys:
        - mingw64
        - mingw32
        - ucrt64  # Experimental!
        - clang64 # Experimental!
  steps:
    - uses: msys2/setup-msys2@v2
      with:
        msystem: ${{matrix.sys}}
        pacboy: openssl:p

Furthermore, .github/workflows/PKGBUILD.yml is a Reusable Workflow to build and test a package in GitHub Actions using a PKGBUILD recipe. It can be used along with matrix (a Composite Action), as shown in .github/workflows/Tool.yml.

Note: By default, GitHub Actions terminates any running jobs if any job in matrix fails. This default behavior can be disabled by setting fail-fast: false in strategy section. See docs.github.com: jobs.<job_id>.strategy.fail-fast for more details.

Find similar patterns in the following workflows:

Find further details at #171 and #102.

Options

msystem

By default, MSYSTEM is set to MINGW64. However, an optional parameter named msystem is supported, which expects MSYS, MINGW64, MINGW32, UCRT64, CLANG32 or CLANG64. For example:

  - uses: msys2/setup-msys2@v2
    with:
      msystem: MSYS

Furthermore, the environment variable can be overridden. This is useful when multiple commands need to be executed in different contexts. For example, in order to build a PKGBUILD file and then test the installed artifact:

  - uses: msys2/setup-msys2@v2
    with:
      msystem: MSYS
  - shell: msys2 {0}
    run: |
      makepkg-mingw -sCLfc --noconfirm --noprogressbar
      pacman --noconfirm -U mingw-w64-*-any.pkg.tar.xz
  - run: |
      set MSYSTEM=MINGW64
      msys2 -c '<command to test the package>'

path-type

Defines which parts of the Windows $env:PATH environment variable leak into the MSYS2 environment. Allowed values:

strict: do not inherit anything from $env:PATH.
minimal (default): only inherit the default Windows paths from $env:PATH (so that cmd.exe and powershell.exe are available for example).
inherit: inherit everything; warning: this can lead to interference with other tools installed on the system.

  - uses: msys2/setup-msys2@v2
    with:
      path-type: minimal

This option corresponds to the MSYS2_PATH_TYPE setting in MSYS2; hence it can be set per step through env. See msys2/MSYS2-packages: filesystem/profile for further details about the configuration of each option.

update

By default, the installation is not updated; hence package versions are those of the installation tarball. By setting option update to true, the action will try to update the runtime and packages cleanly:

  - uses: msys2/setup-msys2@v2
    with:
      update: true

install

Installing additional packages after updating the system is supported through option install. The package or list of packages are installed through pacman --noconfirm -S --needed --overwrite *.

  - uses: msys2/setup-msys2@v2
    with:
      update: true
      install: >-
        git
        base-devel

pacboy

Installing additional packages with pacboy after updating the system is supported through option pacboy. The package or list of packages are installed through pacboy --noconfirm -S --needed.

  strategy:
    fail-fast: false
    matrix:
      sys: [ MINGW64, MINGW32, UCRT64, CLANG64 ]
  steps:
  - uses: msys2/setup-msys2@v2
    with:
      msystem: ${{matrix.sys}}
      install: >-
        git
        base-devel
      pacboy: >-
        openssl:p

release

By default (true), retrieve and extract base installation from upstream GitHub Releases. If set to false, the installation available in the virtual environment is used:

  - uses: msys2/setup-msys2@v2
    with:
      release: false

location

Specify the location where to install msys2:

  - uses: msys2/setup-msys2@v2
    with:
      location: D:\

platform-check-severity

By default (fatal), throw an error if the runner OS is not Windows. If set to warn, simply log a message and skip the rest:

  - uses: msys2/setup-msys2@v2
    with:
      platform-check-severity: warn

txtsd / setup-msys2