156 lines
6.5 KiB
Markdown
156 lines
6.5 KiB
Markdown
|
# Vcpkg and Mingw-w64
|
||
|
|
|
||
|
|
**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/mingw.md).**
|
||
|
|
|
||
|
|
*MinGW is not tested as part of vcpkg repository's CI process, so regressions can occur as part of library updates. PRs improving support are welcome!*
|
||
|
|
|
||
|
|
## Table of Contents
|
||
|
|
|
||
|
|
- [Mingw-w64 community triplets](#mingw-w64-community-triplets)
|
||
|
|
- [Using Mingw-w64 natively on Windows](#mingw-native)
|
||
|
|
- [How to avoid mixing different installations](#how-to-avoid-mixing-different-installations)
|
||
|
|
- [Using Mingw-w64 to build Windows programs on other systems](#mingw-cross)
|
||
|
|
|
||
|
|
## Mingw-w64 community triplets
|
||
|
|
|
||
|
|
Vcpkg includes
|
||
|
|
[x64, x86, arm64 and arm community triplets](https://github.com/microsoft/vcpkg/tree/master/triplets/community)
|
||
|
|
for [Mingw-w64](http://mingw-w64.org/). 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](https://github.com/microsoft/vcpkg/discussions?discussions_q=mingw)
|
||
|
|
- [Open issues](https://github.com/microsoft/vcpkg/issues?q=is%3Aissue+is%3Aopen+mingw)
|
||
|
|
- [Open pull requests](https://github.com/microsoft/vcpkg/pulls?q=is%3Apr+is%3Aopen+mingw)
|
||
|
|
|
||
|
|
<a id="mingw-native"></a>
|
||
|
|
## Using Mingw-w64 natively on Windows
|
||
|
|
|
||
|
|
With [MSYS2](https://www.msys2.org/), 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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
export VCPKG_DEFAULT_TRIPLET=x64-mingw-dynamic
|
||
|
|
export VCPKG_DEFAULT_HOST_TRIPLET=x64-mingw-dynamic
|
||
|
|
```
|
||
|
|
|
||
|
|
Now you can test your setup:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
./vcpkg install zlib
|
||
|
|
```
|
||
|
|
|
||
|
|
### How to avoid mixing different installations
|
||
|
|
|
||
|
|
[The MSYS2 project explicitly warns](https://www.msys2.org/wiki/MSYS2-introduction/#path)
|
||
|
|
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:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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`.
|
||
|
|
|
||
|
|
<a id="mingw-cross"></a>
|
||
|
|
## 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](https://repology.org/projects/?search=-mingw-w64)
|
||
|
|
or [prefix](https://repology.org/projects/?search=mingw-w64-).
|
||
|
|
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](https://mxe.cc/).
|
||
|
|
|
||
|
|
For vcpkg bootstrapping, clone the github repository and run the
|
||
|
|
`bootstrap-vcpkg.sh` script:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
git clone https://github.com/microsoft/vcpkg.git
|
||
|
|
cd vcpkg
|
||
|
|
./bootstrap-vcpkg.sh
|
||
|
|
./vcpkg install zlib:x64-mingw-dynamic
|
||
|
|
```
|
||
|
|
|