diff --git a/README.md b/README.md new file mode 100644 index 0000000..cce7f25 --- /dev/null +++ b/README.md @@ -0,0 +1,278 @@ +
+ +# Setup MSYS2 + +**setup-msys2** is a JavaScript GitHub Action (GHA) to setup an [MSYS2](https://www.msys2.org/) environment (i.e. MSYS, +MINGW32, MINGW64, UCRT64, CLANG32, CLANG64 and/or CLANGARM64 shells) using the GHA [toolkit](https://github.com/actions/toolkit) for +automatic caching. + +## Context + +[MSYS2](https://www.msys2.org/) is available by default on the [windows-latest](https://github.com/actions/virtual-environments/blob/main/images/win/Windows2019-Readme.md#msys2) +[virtual environment](https://github.com/actions/virtual-environments) 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](https://github.com/actions/virtual-environments/issues/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](http://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](https://github.com/actions/virtual-environments/issues/1525)). + +## Usage + +```yaml + - uses: msys2/setup-msys2@v2 +``` + +Then, for scripts: + +```yaml + - 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: + +```yaml + - shell: powershell + run: msys2 -c 'uname -a' +``` + +```yaml + - 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: + +```yaml + 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@v3 + - run: git describe --dirty +``` + +Note that setting `autocrlf` is required in specific use cases only. +See [actions/checkout#250](https://github.com/actions/checkout/issues/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](https://docs.github.com/en/actions/configuring-and-managing-workflows/configuring-a-workflow#configuring-a-build-matrix) +and [docs.github.com: `jobs.