From b36bb4097135abea9f5bff7ddc3f488fac434278 Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Feb 03 2023 11:06:30 +0000 Subject: mingw: add docs about ucrt64 build target This was introduced in F37 https://fedoraproject.org/wiki/Changes/F37MingwUCRT Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index c252926..10e25fc 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -13,7 +13,10 @@ 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. +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. == Track Fedora native package versions @@ -35,14 +38,15 @@ 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+` or -`+%files -n mingw64-foo+`. +packages are created by sections with `+%files -n mingw32-foo+`, +`+%files -n mingw64-foo+` or `+%files -n ucrt64-foo+`. [cols=",",] |======================================================= |`+mingw-+` |Used for source package and RPM spec name -|`+mingw32-+` |Used for packages which are built for Win32 -|`+mingw64-+` |Used for packages which are built for Win64 +|`+mingw32-+` |Used for packages which are built for Win32 with the MSVCRT runtime +|`+mingw64-+` |Used for packages which are built for Win64 with the MSVCRT runtime +|`+ucrt64-+` |Used for packages which are built for Win64 with the UCRT runtime |======================================================= == Base packages @@ -55,11 +59,11 @@ packages should BuildRequire `+mingw32-filesystem+`, `+mingw64-filesystem+`, [cols=",",] |================================================================================================================================================================================================================================= -|`+mingw32-filesystem+` / `+mingw64-filesystem+` |Core filesystem directory layout, and RPM macros for spec files. Equivalent to 'filesystem' RPM -|`+mingw32-binutils+` / `+mingw64-binutils+` |Cross-compiled binutils (utilities like 'strip', 'as', 'ld') which understand Windows executables and DLLs. Equivalent to 'binutils' RPM -|`+mingw32-gcc+` / `+mingw64-gcc+` |GNU compiler collection. Compilers for C and C++ which cross-compile to a Windows target. Equivalent to gcc RPM -|`+mingw32-crt+` / `+mingw64-crt+` |Base libraries for core MinGW runtime & development environment. Equivalent to 'glibc' RPM -|`+mingw32-headers+` / `+mingw64-headers+` |Win32 and Win64 API. A free (public domain) reimplementation of the header files required to link to the Win32 and Win64 API. No direct equivalent in base Fedora - glibc-devel is closest +|`+mingw32-filesystem+` / `+mingw64-filesystem+` / `+ucrt64-filesystem+` |Core filesystem directory layout, and RPM macros for spec files. Equivalent to 'filesystem' RPM +|`+mingw32-binutils+` / `+mingw64-binutils+` / `+ucrt64-binutils+` |Cross-compiled binutils (utilities like 'strip', 'as', 'ld') which understand Windows executables and DLLs. Equivalent to 'binutils' RPM +|`+mingw32-gcc+` / `+mingw64-gcc+` / `+ucrt64-gcc+` |GNU compiler collection. Compilers for C and C++ which cross-compile to a Windows target. Equivalent to gcc RPM +|`+mingw32-crt+` / `+mingw64-crt+` / `+ucrt64-crt+` |Base libraries for core MinGW runtime & development environment. Equivalent to 'glibc' RPM +|`+mingw32-headers+` / `+mingw64-headers+` / `+ucrt64-headers+` |Win32 and Win64 API. A free (public domain) reimplementation of the header files required to link to the Win32 and Win64 API. No direct equivalent in base Fedora - glibc-devel is closest |================================================================================================================================================================================================================================= == Build for multiple targets @@ -70,24 +74,28 @@ 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 a MinGW package will be built for both the Win32 and Win64 targets. +By default a MinGW package 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 either one of these targets this can be -indicated by setting one of these: +When a package can only be built for a subset of these targets this can be +indicated by setting one or more of these: [cols=",",] |=============================================================== -|`+%global mingw_build_win32 0+` |Don't build for the Win32 target -|`+%global mingw_build_win64 0+` |Don't build for the Win64 target +|`+%global mingw_build_win32 0+` |Don't build for the Win32 target with the MSVCRT runtime +|`+%global mingw_build_win64 0+` |Don't build for the Win64 target with the MSVCRT runtime +|`+%global mingw_build_ucrt64 0+` |Don't build for the Win64 target with the UCRT runtime |=============================================================== == One source RPM, separate binary RPMs per-target 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 `+foo+` builds binaries for the Win32 and Win64 targets, then the -source RPM should provide two subpackages named `+mingw32-foo+` and -`+mingw64-foo+`. +package `+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. @@ -103,14 +111,16 @@ like this: %mingw_find_lang foo .... -then two files will get created named `+mingw32-foo.lang+` and -`+mingw64-foo.lang+`. These file lists can be included in the %files section -for the targets: +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: .... %files -n mingw32-foo -f mingw32-foo.lang %files -n mingw64-foo -f mingw64-foo.lang + + %files -n ucrt64-foo -f ucrt64-foo.lang .... == Filesystem layout @@ -138,6 +148,9 @@ Integration into the main root filesystem layout is as follows: | +- x86_64-w64-mingw32-cpp | +- x86_64-w64-mingw32-gcc | +- x86_64-w64-mingw32-g++ + | +- x86_64-w64-mingw32ucrt-cpp + | +- x86_64-w64-mingw32ucrt-gcc + | +- x86_64-w64-mingw32ucrt-g++ | +- ... etc.. | +- lib @@ -149,12 +162,14 @@ Integration into the main root filesystem layout is as follows: | +- mingw-find-provides.sh - extra DLL names | +- mingw-find-requires.sh - discover required DLL names | - +- i686-w64-mingw32 - root of mingw toolchain and binaries for the Win32 target - see next diagram - +- x86_64-w64-mingw32 - root of mingw toolchain and binaries for the Win64 target - see next diagram+` + +- i686-w64-mingw32 - root of mingw toolchain and binaries for the Win32 target with MSVCRT runtime - see next diagram + +- x86_64-w64-mingw32 - root of mingw toolchain and binaries for the Win64 target with MSVCRT runtime - see next diagram+` + +- x86_64-w64-mingw32urt - root of mingw toolchain and binaries for the Win64 target with UCRT runtime - see next diagram+` .... The bulk of the packaged content is located under the respective MinGW root, -one of `+/usr/i686-w64-mingw32+` + `+/usr/x86_64-w64-mingw32+`: +one of `+/usr/i686-w64-mingw32+`, `+/usr/x86_64-w64-mingw32+` and +`+/usr/x86_64-w64-mingw32ucrt+`: .... [mingw-root] @@ -192,7 +207,7 @@ 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 -are named: +with the MSVCRT runtime are named: .... %{_bindir}/i686-w64-mingw32-gcc @@ -216,8 +231,10 @@ name, i.e., etc. .... -The same also applies for the x86_64 target. This target uses -'x86_64-w64-mingw32' as prefix instead of 'i686-w64-mingw32' +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'. == Naming of the root filesystem @@ -226,18 +243,26 @@ 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 is provided by the macro: +The location for Win32 target with MSVCRT runtime is provided by the macro: .... %{mingw32_sysroot} %{_prefix}/i686-w64-mingw32/sys-root .... -And the Win64 target is provided by the macro: +The Win64 target with MSVCRT runtime is provided by the macro: .... %{mingw64_sysroot} %{_prefix}/x86_64-w64-mingw32/sys-root .... +The Win64 target with UCRT runtime is provided by the macro: + +.... + %{ucrt64_sysroot} %{_prefix}/x86_64-w64-mingw32ucrt/sys-root +.... + + + == Standard mingw RPM macros The `+mingw-filesystem+` package provides a number of convenience macros for @@ -268,7 +293,7 @@ Generic macros: |mingw_strip |>= 95 |cross compiler 'strip' binary (which supports both Win32 and Win64 binaries) |================================================================================================================================================== -Win32 specific macros: +Win32 with MSVCRT runtime specific macros: [cols=",,,",] |=================================================================================================================================================== @@ -293,7 +318,7 @@ Win32 specific macros: |mingw32_target |>= 95 |i686-w64-mingw32 |Target platform for build |=================================================================================================================================================== -Win64 specific macros: +Win64 with MSVCRT runtime specific macros: [cols=",,,",] |=================================================================================================================================================== @@ -318,12 +343,37 @@ Win64 specific macros: |mingw64_target |>= 95 |x86_64-w64-mingw32 |Target platform for build |=================================================================================================================================================== +Win64 with UCRT runtime specific macros: + +[cols=",,,",] +|=================================================================================================================================================== +|Macro |Available in ucrt64-filesystem | Value |Explanation +|ucrt64_ar |>= 133 |x86_64-w64-mingw32ucrt-ar |cross compiler 'ar' binary +|ucrt64_cc |>= 133 |x86_64-w64-mingw32ucrt-gcc |cross compiler 'gcc' binary +|ucrt64_cflags |>= 133 |-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions --param=ssp-buffer-size=4 |Default compiler flags for C/C++ binaries +|ucrt64_cmake |>= 133 | |Call the 'cmake' binary for the Win64 target +|ucrt64_configure |>= 133 | |standard invocation for autotools 'configure' scripts +|ucrt64_cpp |>= 133 |x86_64-w64-mingw32ucrt-gcc -E |cross compiler 'cpp' binary +|ucrt64_env |>= 133 | |Set the correct environment variables for the Win64 target +|ucrt64_host |>= 133 |x86_64-w64-mingw32 |Host platform for build +|ucrt64_meson |>= 104 | |Call the meson binary for the Win64 target +|ucrt64_ninja |>= 104 | |Call the ninja binary for the Win64 target +|ucrt64_objcopy |>= 133 |x86_64-w64-mingw32ucrt-objcopy |cross compiler 'objcopy' binary +|ucrt64_objdump |>= 133 |x86_64-w64-mingw32ucrt-objdump |cross compiler 'objdump' binary +|ucrt64_pkg_config |>= 133 |x86_64-w64-mingw32ucrt-pkg-config |Call the pkg-config command for the Win64 target +|ucrt64_qmake_qt4 |>= 133 |ucrt64-qmake-qt4 |Call the Qt4 qmake command for the Win64 target +|ucrt64_qmake_qt5 |>= 133 |ucrt64-qmake-qt5 |Call the Qt5 qmake command for the Win64 target +|ucrt64_ranlib |>= 133 |x86_64-w64-mingw32ucrt-ranlib |cross compiler 'ranlib' binary +|ucrt64_strip |>= 133 |x86_64-w64-mingw32ucrt-strip |cross compiler 'strip' binary +|ucrt64_target |>= 133 |x86_64-w64-mingw32 |Target platform for build +|=================================================================================================================================================== + === Filesystem location macros The following macros are for use in %build, %install and %files sections of the RPM spec -For the Win32 target: +For the Win32 with MSVCRT runtime target: [cols=",,",] |=================================================================================================== @@ -341,7 +391,7 @@ For the Win32 target: |mingw32_sysroot |%\{_prefix}/i686-w64-mingw32/sys-root |Windows system root. |=================================================================================================== -For the Win64 target: +For the Win64 with MSVCRT runtime target: [cols=",,",] |=================================================================================================== @@ -359,6 +409,24 @@ For the Win64 target: |mingw64_sysroot |%\{_prefix}/x86_64-w64-mingw32/sys-root |Windows system root. |=================================================================================================== +For the Win64 with UCRT runtime target: + +[cols=",,",] +|=================================================================================================== +|ucrt64_bindir |%\{ucrt64_prefix}/bin |Location of Windows executables. +|ucrt64_datadir |%\{ucrt64_prefix}/share |Shared data used under Windows. +|ucrt64_docdir |%\{ucrt64_prefix}/share/doc |Documentation. +|ucrt64_infodir |%\{ucrt64_prefix}/share/info |Info files (see note below). +|ucrt64_includedir |%\{ucrt64_prefix}/include |Header files used when cross-compiling for Windows. +|ucrt64_libdir |%\{ucrt64_prefix}/lib |Windows libraries (see sections below). +|ucrt64_libexecdir |%\{ucrt64_prefix}/libexec | +|ucrt64_mandir |%\{ucrt64_prefix}/share/man |Man pages (see note below). +|ucrt64_prefix |%\{ucrt64_sysroot}/mingw |Windows equivalent of %\{_prefix}, required by MinGW. +|ucrt64_sbindir |%\{ucrt64_prefix}/sbin | +|ucrt64_sysconfdir |%\{ucrt64_prefix}/etc |Configuration files used when running under Windows. +|ucrt64_sysroot |%\{_prefix}/x86_64-w64-mingw32ucrt/sys-root |Windows system root. +|=================================================================================================== + == Compilation of binaries In order to build binaries for multiple targets we have to call commands like @@ -545,11 +613,11 @@ found in Fedora native packages. These files should not be packaged in the MinGW package. The following files don't need to be packaged in the MinGW package when their native counterpart already contains them: -* Man pages (`+%{mingw32_mandir}+` / `+%{mingw64_mandir}+`) -* Info files (`+%{mingw32_infodir}+` / `+%{mingw64_infodir}+`) -* Generic documentation (`+%{mingw32_docdir}+` / `+%{mingw64_docdir}+`) -* Autoconf files (`+%{mingw32_datadir}/aclocal+` / `+%{mingw64_datadir}/aclocal+`) -* gtk-doc files (`+%{mingw32_datadir}/gtk-doc+` / `+%{mingw64_datadir}/gtk-doc+`) +* Man pages (`+%{mingw32_mandir}+` / `+%{mingw64_mandir}+` / `+%{ucrt64_mandir}+`) +* Info files (`+%{mingw32_infodir}+` / `+%{mingw64_infodir}+` / `+%{ucrt64_infodir}+`) +* Generic documentation (`+%{mingw32_docdir}+` / `+%{mingw64_docdir}+` / `+%{ucrt64_docdir}+`) +* Autoconf files (`+%{mingw32_datadir}/aclocal+` / `+%{mingw64_datadir}/aclocal+` / `+%{ucrt64_datadir}/aclocal+`) +* gtk-doc files (`+%{mingw32_datadir}/gtk-doc+` / `+%{mingw64_datadir}/gtk-doc+` / `+%{ucrt64_datadir}/gtk-doc+`) Note, generic Documentation aimed at end users, as opposed to developers, should be included where it is likely that application developers will want