vcpkg/docs/users/mingw.md

Vcpkg and Mingw-w64

The latest version of this documentation is available on GitHub.

MinGW is community-supported and not tested as part of vcpkg repository's CI process.

Table of Contents

• Mingw-w64 community triplets
• Using Mingw-w64 natively on Windows
  • How to avoid mixing different installations
• Using Mingw-w64 to build Windows programs on other systems

Mingw-w64 community triplets

Vcpkg includes x64, x86, arm64 and arm community triplets for Mingw-w64. They don't depend on Visual Studio and can be used natively on Windows as well as for cross-compiling on other operating systems. There are two variants of each triplet, selecting between static and dynamic linking. The actual tools (g++ etc.) are expected to be named with particular prefixes.

architecture	vcpkg community triplets	tool name prefix
x64	x64-mingw-dynamic, x64-mingw-static	x86_64-w64-mingw32-
x86	x86-mingw-dynamic, x86-mingw-static	i686-w64-mingw32-
arm64	arm64-mingw-dynamic, arm64-mingw-static	aarch64-w64-mingw32-
arm	arm-mingw-dynamic, arm-mingw-static	armv7-w64-mingw32-

These triplets are not tested by continuous integration, so many ports do not build, and even existing ports may break on port updates. Because of this, community involvement is paramount!

• Discussions
• Open issues
• Open pull requests

Using Mingw-w64 natively on Windows

With MSYS2, it is possible to easily create a full environment for building ports with Mingw-w64 on a Windows PC.

Note that for building software for native windows environments, you must use a mingw subsystem of MSYS2, and install some packages (with a specific prefix) for this subsystem.

architecture	vcpkg triplets	subsystem	package prefix
x64	x64-mingw-dynamic, x64-mingw-static	mingw64	mingw-w64-x86_64-
x86	x86-mingw-dynamic, x86-mingw-static	mingw32	mingw-w64-i686-

After the basic installation of MSYS2, you will need to install a few additional packages for software development, e.g. for x64:

pacman -S --needed git base-devel mingw-w64-x86_64-toolchain

The active subsystem is selected by running the MSYS2 MinGW app, or changed in a running terminal by

source shell mingw64   # for x64, or "mingw32" for x86

The bootstrapping of vcpkg shall be done by running bootstrap-vcpkg.bat. This will download the official vcpkg.exe.

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.bat

For building packages, you need to tell vcpkg that you want to use the mingw triplet. This can be done in different ways. When Visual Studio is not installed, you must also set the host triplet to mingw. This is needed to resolve host dependencies. For convenience, you can use environment variables to set both triplets:

export VCPKG_DEFAULT_TRIPLET=x64-mingw-dynamic
export VCPKG_DEFAULT_HOST_TRIPLET=x64-mingw-dynamic

Now you can test your setup:

./vcpkg install zlib

How to avoid mixing different installations

The MSYS2 project explicitly warns that "mixing in programs from other MSYS2 installations, Cygwin installations, compiler toolchains or even various other programs is not supported and will probably break things in unexpected ways." For example, the proper passing of command line arguments with quoting and escaping may fail.

But Vcpkg ports implicitly create MSYS2 installations, e.g. for pkg-config and for various other build tools needed to deal with packages based on autoconf. In particular, when ports prepend the directory of tools to the PATH environment variable, this may change which tool with a particular name is actually invoked, and how arguments are passed between tools.

To mitigate such issues when working with a full MSYS2 installation, try to keep the directories of the msys subsystem (/usr/bin, bin) out of the PATH environment variable as found by vcpkg. In bash, you may modify the PATH just for a single call of vcpkg:

PATH="${PATH/:\/usr\/bin:\/bin:/:}" ./vcpkg install libpq

Alternatively, you may run vcpkg from a regular Command Prompt, after adding only the desired mingw directory (e.g. C:\msys64\mingw64\bin) to the PATH.

When using vcpkg for CI with standard images on Azure Pipelines, Github Actions or similar, note that the default PATH might contain more directories which create a mix of MSYS2 programs from different installations. You may want to set the desired PATH manually, or remove directories which contain sh.exe, bash.exe, msys-2.0.dll or cygwin1.dll.

Using Mingw-w64 to build Windows programs on other systems

You can use the vcpkg mingw community triplets with toolchains on non-Windows computers to cross-compile software to be run on Windows. Many Linux distributions offer such toolchains in optional packages with a mingw-w64 suffix or prefix. As an example, for Debian-based distributions, you would start with this installation command for the x64 toolchain:

sudo apt-get install gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64

Note that the packaged versions of Mingw-w64 toolchains on Linux distributions might be older releases which lack some useful features or bug fixes. An alternative independent toolchain is offered by MXE.

For vcpkg bootstrapping, clone the github repository and run the bootstrap-vcpkg.sh script:

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg install zlib:x64-mingw-dynamic