Packaging Guidelines for MinGW Cross Compilers

The Fedora MinGW project’s mission is to provide an excellent development environment for Fedora users who wish to cross-compile their programs to run on Windows, minimizing the need to use Windows at all. In the past developers have had to port and compile all of the libraries and tools they have needed, and this huge effort has happened independently many times over. We aim to eliminate duplication of work for application developers by providing a range of libraries and development tools which have already been ported to the MinGW cross-compiler environment. This means that developers will not need to recompile the application stack themselves, but can concentrate just on the changes needed to their own application.

The targets Win32 and Win64 are supported with the MSVCRT runtime. The target Win64 with the UCRT runtime is also supported, however, only for the base toolchain. Builds for UCRT are not enabled for packages above the toolchain at this time.

There are two permitted ways to provide MinGW builds of software in Fedora:

The traditional approach of completely separated source packages was adopted initially because of concerns that instability in the MinGW toolchain or Windows builds may prevent timely updates to the native package. Experience in Fedora since then has shown that is not generally a problem that impacts most packages, especially where Windows support is an explicitly tested deliverable of the upstream project.

Using the separate packaging approach has a significantly higher overhead:

With the integrated packaging approach there is a small extra overhead on the native package maintainer to ensure MinGW builds keep working and a small additional load of MinGW specific bug reports. This is usually negligible compared to the overhead of maintaining separated packages.

With this in mind, the recommendation of the MinGW SIG is thus:

When a corresponding native package does not already exist, it will always be required to go through the standard Fedora new package review process. The proposed MinGW support MUST follow the integrated packaging approach to provide both the MinGW and native builds, where technically possible. As noted in the previous section, in some rare situations there will be no corresponding native package, thus requiring the separate pacakaging approach to be taken.

When a corresponding native package is already present in Fedora, the preference is to add MinGW support to the native source package.

Where the source package changes are simple, the contributor SHOULD:

The existing native package maintainer thus gets clear view of the impact of the MinGW additions to their package, to evaluate the viability of following the integrated packaging approach.

Where there is doubt about the viability of following the integrated package approach, a bug MAY be opened against the package ahead of starting work to discuss the two packaging options with the native package maintainer.

If the native maintainer declines the proposal to add MinGW support to the existing package, the regular Fedora new package process MUST be followed to introduce MinGW support following the separate packaging approach.

In general terms, cross-compiled MinGW versions of packages which are already natively available in Fedora, should follow the native Fedora package as closely as possible. This means they should stay at the same version, include all the same patches as the native Fedora package, and be built with the same configuration options.

The preferred way to achieve this goal is for the MinGW support to use the integrated packaging approach.

Cross compiled MinGW packages must follow Fedora policy, except where noted in this document. Cross compiled packages go through the same review process, GIT admin process etc. as other Fedora packages.

MinGW packages require special naming to denote the appropriate CPU architecture the binaries have been built for. There should never be a package prefixed with mingw- output during a build. The mingw- prefix is exclusive for RPM spec file names and the source RPM file name. The CPU architecture specific packages are created by sections with %files -n mingw32-foo, %files -n mingw64-foo or %files -n ucrt64-foo.

The base packages provide a root filesystem, base libraries, binutils (basic programs like 'strip', 'ld' etc), the compiler (gcc) and the Win32/Win64 API. Packages may need to depend on one or more of these. In particular, almost all packages should BuildRequire mingw32-filesystem, mingw64-filesystem, mingw32-gcc and mingw64-gcc.

The goal of the MinGW framework is to provide an easy way for package maintainers to build their packages for multiple targets using one .spec file. To aid developers in this several RPM macros have been developed which are part of the mingw-filesystem package. These RPM macros will be explained later on in these guidelines.

By default MinGW support will be built for both the Win32 and Win64 targets with the MSVCRT runtime. Building of the Win64 target with the UCRT64 runtime is not yet enabled by default.

When a package can only be built for a subset of these targets this can be indicated by setting one or more of these:

Each cross compiled MinGW package which builds binaries for a specific target should put the binaries for that target in a separate subpackage. So if a package mingw-foo or foo builds binaries for the Win32 and Win64 targets with the MSVCRT runtime, then the source RPM should provide two subpackages named mingw32-foo and mingw64-foo. If a package builds for the UCRT runtime, it will also have a ucrt64-foo subpackage.

This means that a spec file must contains %package and %files sections for all the targets.

When using the separate packaging approach, packages containing translations must use %mingw_find_lang instead of %find_lang.

When using the integrated packaging approach, packages containing translations must use +%find_lang followed by %mingw_find_lang.

This causes all translation filelists to be split in per-target filelists. For example: when a spec file contains something like this:

then one file per mingw target will get created named mingw32-foo.lang, mingw64-foo.lang, and ucrt64-foo.lang. These file lists can be included in the %files section for the targets:

Integration into the main root filesystem layout is as follows:

The bulk of the packaged content is located under the respective MinGW root, one of /usr/i686-w64-mingw32, /usr/x86_64-w64-mingw32 and /usr/x86_64-w64-mingw32ucrt:

The MinGW cross-compilers and binutils are Fedora binaries and are therefore placed in %{_bindir} (i.e., /usr/bin) according to the FHS and Fedora guidelines.

The MinGW cross-compilers and binutils which generate i686 binaries for Windows with the MSVCRT runtime are named:

The same binaries are present in %{_prefix}/i686-w64-mingw32/bin without any prefix in the name, i.e.,

The same also applies for the x86_64 target with both MSVCRT and UCRT runtimes. The target with MSVCRT uses 'x86_64-w64-mingw32' as prefix instead of 'i686-w64-mingw32', while UCRT uses 'x86_64-w64-mingw32ucrt'.

The root filesystem contains Windows executables and DLLs and any other Windows-only files. It is necessary both because we need to store Windows libraries in order to link further libraries which depend on them, and also because MinGW requires a root filesystem location.

The location for Win32 target with MSVCRT runtime is provided by the macro:

The Win64 target with MSVCRT runtime is provided by the macro:

The Win64 target with UCRT runtime is provided by the macro:

The mingw-filesystem package provides a number of convenience macros for the cross compiled sysroot directories, and toolchain. It is mandatory to use these macros in all MinGW cross compiled packages submitted to Fedora.

In order to build binaries for multiple targets we have to call commands like ./configure and make multiple times (once for each target). If one has to write this all out in a spec file then it will lead to duplicate code. To reduce the amount of duplication, several RPM macros have been introduced to help with the compilation. These macros are %mingw_configure, %mingw_cmake, %mingw_cmake_kde4, %mingw_qmake_qt4, %mingw_qmake_qt5 and %mingw_make

These macros use out of source compilation to build binaries for all the targets. Almost all packages support out of source compilation or require slight patching. The only known exceptions to date are zlib and openssl. Packages which don’t support out of source compilation may require a different approach like performing everything in the %install phase. If you happen to stumble across a package which requires a different approach feel free to contact us on the Fedora MinGW mailing list

Some packages need to be built multiple times for each target. Examples of this are packages which have to be built once for a static version and once for a shared version. Such packages can add a custom suffix to the build directory used. Say you’ve got something like below:

This can be rewritten to something like this:

Most packages used the command make %{?_smp_mflags} to build the package. In the MinGW cross compiler framework you have to use %mingw_make %{?_smp_mflags} to build the package for all configured targets. As with the %mingw_configure macro you can also use the MINGW_BUILDDIR_SUFFIX environment variable to indicate a custom suffix to the build directory used

To install the package the command make install DESTDIR=$RPM_BUILD_ROOT was used in almost all cases. This can be rewritten to %mingw_make install DESTDIR=$RPM_BUILD_ROOT to install the package for all configured targets. The environment variable MINGW_BUILDDIR_SUFFIX can also be used here.

Some packages require some custom instructions before the files are ready to be packaged. Such code can remain as is. However, you may need to duplicate these instructions multiple times (for all configured targets).

If a package contains binaries which depend on a DLL provided by another package, these dependencies should be expressed in the form:

where foo.dll is the name of the DLL. The name must be converted to lowercase because Windows binaries contain case insensitive dependencies. The form 'mingw32(foo.dll)' should be used for Win32 binaries and the form 'mingw64(foo.dll)' for Win64 binaries.

Correct dependency generation is done automatically. Packagers should start their spec files with this line:

All binary packages should depend on mingw32-filesystem or mingw64-filesystem (depending on the files in the package).

All specfiles should BuildRequire at least one of these (depending on the targets for which you want to build):

and any other BuildRequires that they need.

Most mingw RPM macros can be assumed to exist in all non-EOL Fedora releases. If the package does, however, rely on a newly introduced macro, a versioned dependancy on the mingw-XX-filesystem packages should be used.

All packages should have:

unless they contain Fedora native executables. Where using the separate packaging approach, the BuildArch tag must be present in the common spec file header. Where using the integrated packaging approach, the BuildArch tag must be present under the %package header for each MinGW sub-RPM that is present.

All libraries must be built as DLLs.

Because of the peculiarity of Windows, DLLs are stored in the %{mingw32_bindir} directory, along with a control file in the %{mingw32_libdir} directory. For example, for a library called foo there would be:

The foo.dll file is the main library, foo.dll.a is a stub linked to applications so they can find the library at runtime. All of these files are required in those locations in order to link successfully. The .dll may contain a version number although not always (e.g., foo-0.dll).

The MinGW packages are intended to allow developers to compile and test the Windows support of their applications. It is furthermore expected that developers will build Windows installers (MSIs) for their applications using the MinGW package content.

Thus the Fedora MinGW package file listing must include content needed to satisfy either build/test usage or the creation of Windows installers.

In general it it possible to convert in either direction between the separate and integrated packaging approaches. Both approaches result in the exact same binary RPMs for MinGW content, only differing in their source RPM specfile.

To convert from separate to integrated packaging

To convert from integrated to separate packaging

In both cases the upgrade experience should be transparent to users installing and updating Fedora deployments.

It is recommended that such conversions only be performed in Rawhide. If there is need to do a conversion from integrated to separate packaging in a stable release stream, a single Bohdi update must include both the native and mingw package builds.

When using the integrated packaging approach it MUST be possible to disable the build of MinGW sub-RPMs, and the build MUST be disabled by default except for the Fedora distribution target. This ensures that the native package can still be built in derivative distros, such as RHEL, where the MinGW toolchains not included. This is achieved by including a conditional near the top of the specfile:

and then wrapping all MinGW related %package / +%files definitions and relevant %build or %install commands in a conditional check:

The separate package specfile essentially extracts all the content within the %{with mingw} conditionals from the previous example, and puts it into a standalone specfile.