PackagingDrafts/MinGWCrossCompiler

= Packaging Guidelines for MinGW Cross Compilers =

= Introduction =

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.

As of Fedora 16 a set of RPM macros and packages have been introduced which help packagers compile binaries for multiple targets. The targets Win32 and Win64 will be supported.

= Track Fedora native package versions =

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 MinGW SIG have written an RPM comparison tool which makes it possible to compare cross compiled MinGW packages with the Fedora native packages, in order to determine whether versions, patches and configuration are aligned.

= Follow Fedora policy =

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.

= Package naming =

MinGW source packages should be named by prefixing the Fedora native package name with. The packages generated from this should be prefixed according to which platform they're being built for:

= Base packages =

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,   and. The correct Requires flags will get added automatically when the __find_requires macro is overridden (as will be described later on in these guidelines)

= Build for multiple targets =

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.

Several RPM macros depend on the package name minus the prefix, so each package must contain  (where   is the name of the package, for example glib2)

To indicate which targets should be build, the package must contain at least one of the following lines:

= 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  builds binaries for the Win32 and Win64 targets, then the source RPM should provide two subpackages named   and.

The main package ( in our example) must have   tags for all the targets. To aid in this, the RPM macro  should be added to the spec file.

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

If a package contains translations then all calls to the  must be replaced by. This causes all translation filelists to be split in per-target filelists. For example: when a spec file contains something like this: %global mingw_build_win32 1 %global mingw_build_win64 1 %install %mingw_find_lang foo then two files will get created named  and. 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

= Filesystem layout =

[root] |  +- etc |  |   |   +- rpm |      |   |       +- macros.mingw |      +- macros.mingw32 |      +- macros.mingw64 |  +- usr |      +- bin   - Links to MinGW cross compiler toolchain |  |       |   +- i686-w64-mingw32-cpp |  +- i686-w64-mingw32-gcc |  +- i686-w64-mingw32-g++ |  +- x86_64-w64-mingw32-cpp |  +- x86_64-w64-mingw32-gcc |  +- x86_64-w64-mingw32-g++ |  +- ... etc.. |      +- lib |  |       |   +- rpm |      |       |       +- mingw-find-debuginfo.sh - extract debug information from Win32 and Win64 binaries |      +- mingw-find-lang.sh - generates per-target file lists containing translations |      +- 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

/usr/i686-w64-mingw32 /usr/x86_64-w64-mingw32 |  +- bin  - Binutils toolchain binaries for the target |  |   |   +- ar   |   +- as   |   +- dlltool |  +- ld   |   +- ... etc ... |  +- lib  - Binutils toolchain support libraries / files for the target |  +- sys-root  - root for cross compiled MinGW binaries |      +- mingw |          +- bin     - cross-compiled MinGW binaries & runtime DLL parts +- etc    - configuration files +- include - include files for cross compiled MinGW libs +- lib    - cross-compiled static MinGW libraries & linktime DLL parts |  |           |   +- pkgconfig  - pkg-config definitions for libraries |          +- share |              +- man

= Filenames of the cross-compilers and binutils =

The MinGW cross-compilers and binutils are Fedora binaries and are therefore placed in  (ie.  ) according to the FHS and Fedora guidelines.

The MinGW cross-compilers and binutils which generate i686 binaries for Windows are named: %{_bindir}/i686-w64-mingw32-gcc %{_bindir}/i686-w64-mingw32-g++ %{_bindir}/i686-w64-mingw32-ld %{_bindir}/i686-w64-mingw32-as %{_bindir}/i686-w64-mingw32-strip etc.

The same binaries are present in without any prefix in the name, ie: %{_prefix}/i686-w64-mingw32/bin/gcc %{_prefix}/i686-w64-mingw32/bin/g++ %{_prefix}/i686-w64-mingw32/bin/ld %{_prefix}/i686-w64-mingw32/bin/as %{_prefix}/i686-w64-mingw32/bin/strip etc.

The same also applies for the x86_64 target. This target uses 'x86_64-w64-mingw32' as prefix instead of 'i686-w64-mingw32'

= Naming of the root filesystem =

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 is provided by the macro: %{mingw32_sysroot}  %{_prefix}/i686-w64-mingw32/sys-root And the Win64 target is provided by the macro: %{mingw64_sysroot}  %{_prefix}/x86_64-w64-mingw32/sys-root

= Standard mingw RPM macros =

The  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.

Toolchain macros
The following macros are for the %build and %install section of the spec

Generic macros:

Win32 specific macros:

Win64 specific macros:

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 Win64 target:

= Compilation of binaries =

In order to build binaries for multiple targets we have to call commands like  and   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,  ,   and

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

There's a difference in the behavior between these macros and the original  macros. As all commands will get executed multiple times (once for each target) arguments to the macros cannot be given if the macro is in curly braces. One has to invoke the macro without curly braces for things to work. For example, with the original Fedora MinGW toolchain you could do: %{mingw32_configure} --disable-xlib --enable-win32 This has to be changed to something like this: %mingw_configure --disable-xlib --enable-win32 Note that the '{' '}' characters need to be omitted from the mingw_configure macro in this case.

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: mkdir build_shared pushd build_shared %{mingw32_configure} --enable-shared popd mkdir build_static pushd build_static %{mingw32_configure} --enable-static popd This can be rewritten to something like this: %mingw_configure -s shared --enable-shared %mingw_configure -s static --enable-static

Most packages used the command  to build the package. In the MinGW cross compiler framework you have to use  to build the package for all configured targets As with the  macro you can also use the   argument to indicate a custom suffix to the build directory used

To install the package the command  was used in almost all cases. This can be rewritten to  to install the package for all configured targets The  argument 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).

= Dependencies =

If a package contains binaries which depend on a DLL provided by another package, these dependencies should be expressed in the form: mingw32(foo.dll) where  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 include these lines in all library packages: %global _use_internal_dependency_generator 0 %global __find_requires %{mingw_findrequires} %global __find_provides %{mingw_findprovides} All binary packages should depend on  or   (depending on the files in the package). If the lines mentioned above are used then it will be added automatically, so you don't have to add it yourself

All specfiles should BuildRequire at least:

BuildRequires: mingw-filesystem >= minimum-version

and any other BuildRequires that they need.

= Build architecture =

All packages should have:

BuildArch: noarch

unless they contain Fedora native executables.

= Libraries (DLLs) =

All libraries must be built as DLLs.

Because of the peculiarity of Windows, DLLs are stored in the  directory, along with a control file in the   directory. For example, for a library called  there would be: %{mingw32_bindir}/foo.dll %{mingw32_libdir}/foo.dll.a %{mingw32_libdir}/foo.la The  file is the main library,   is a stub linked to applications so they can find the library at runtime, and   is a libtool archive so that libtool can link to dependent libraries at build time. All of these files are required in those locations in order to link successfully. The  may contain a version number although not always (eg.  ).

Do not use %{mingw32_bindir}/* or %{mingw32_libdir}/* in %files section
The  section must list DLLs separately. Packages must NOT use  or

The reason for this is that libtool is very fragile and will give up on building a DLL very easily. Therefore we force the name of the DLL to be listed explicitly in the  section in order to catch this during RPM builds.

Manpages and info files
If manpages or info files are simply duplicates of equivalent documentation found in Fedora native packages, then they should not be packaged in the MinGW package.

Stripping
Libraries and executables should be stripped. This is done correctly and automatically if the spec file includes these lines:

%global __strip %{mingw_strip} %global __objdump %{mingw_objdump}

(Note that if __strip and __objdump are not overridden in the specfile then this can sometimes cause Windows binaries to become corrupted).

Debuginfo subpackage
Most binaries contain debugging symbols when the package gets built. To split the debugging symbols to a separate debuginfo package (as is done with native Fedora packages) the spec file must include these lines: %define __debug_install_post %{mingw_debug_install_post} %{?mingw_debug_package} Note that  really must be used here. If you use  then the automatic generation of a debuginfo subpackage won't work.

Example Specfile
%global __strip %{mingw_strip} %global __objdump %{mingw_objdump} %global _use_internal_dependency_generator 0 %global __find_requires %{mingw_findrequires} %global __find_provides %{mingw_findprovides} %define __debug_install_post %{mingw_debug_install_post}

%global mingw_pkg_name example %global mingw_build_win32 1 %global mingw_build_win64 1

Name:          mingw-example Version:       1.0.0 Release:       1%{?dist} Summary:       MinGW compiled example library

License:       LGPLv2+ Group:         Development/Libraries URL:           http://fedoraproject.org Source0:       http://fedoraproject.org/example-%{version}.tar.bz2

BuildArch:     noarch

BuildRequires: mingw-filesystem >= 65 BuildRequires: mingw32-gcc BuildRequires: mingw64-gcc BuildRequires: mingw32-binutils BuildRequires: mingw32-binutils BuildRequires: mingw32-gettext BuildRequires: mingw64-gettext BuildRequires: mingw32-win-iconv BuildRequires: mingw64-win-iconv BuildRequires: mingw32-zlib BuildRequires: mingw64-zlib

%{?mingw_debug_package}

%description MinGW compiled example library.

%package -n mingw32-%{mingw_pkg_name} Summary:      %{summary}
 * 1) Mingw32

%description -n mingw32-%{mingw_pkg_name} MinGW compiled example library.

%package -n mingw64-%{mingw_pkg_name} Summary:      %{summary}
 * 1) Mingw64

%description -n mingw64-%{mingw_pkg_name} MinGW compiled example library.

%package -n mingw32-%{mingw_pkg_name}-static Summary:      Static version of the MinGW compiled example library Requires:     mingw32-%{mingw_pkg_name} = %{version}-%{release}
 * 1) If a package maintainer wishes to bundle static libraries then they
 * 2) can be placed in -static subpackages. Otherwise, these subpackages
 * 3) can be dropped

%description -n mingw32-%{mingw_pkg_name}-static Static version of the MinGW compiled example library.

%package -n mingw64-%{mingw_pkg_name}-static Summary:      Static version of the MinGW compiled example library Requires:     mingw64-%{mingw_pkg_name} = %{version}-%{release}

%description -n mingw64-%{mingw_pkg_name}-static Static version of the MinGW compiled example library.

%prep %setup -q -n %{mingw_pkg_name}-%{version}

%build %mingw_configure "--enable-static" "--enable-shared" "--enable-foo" %mingw_make %{?_smp_mflags}

%install %mingw_make_install "DESTDIR=$RPM_BUILD_ROOT"

%mingw_find_lang %{mingw_pkg_name}


 * 1) Note: there should be no %%files section for the main package!

%files -n mingw32-%{mingw_pkg_name} -f mingw32-%{mingw_pkg_name}.lang %defattr(-,root,root,-) %{mingw32_bindir}/libexample-0.dll %{mingw32_includedir}/example/ %{mingw32_libdir}/libexample.dll.a %{mingw32_libdir}/libexample.la %{mingw32_libdir}/pkgconfig/example.pc
 * 1) Win32

%files -n mingw64-%{mingw_pkg_name} -f mingw64-%{mingw_pkg_name}.lang %defattr(-,root,root,-) %{mingw64_bindir}/libexample-0.dll %{mingw64_includedir}/example/ %{mingw64_libdir}/libexample.dll.a %{mingw64_libdir}/libexample.la %{mingw64_libdir}/pkgconfig/example.pc
 * 1) Win64

%files -n mingw32-%{mingw_pkg_name}-static %defattr(-,root,root,-) %{mingw32_libdir}/libexample.a
 * 1) Static subpackages are optional (as mentioned earlier)
 * 2) Win32

%files -n mingw64-%{mingw_pkg_name}-static %defattr(-,root,root,-) %{mingw64_libdir}/libexample-0.a
 * 1) Win64

%changelog - Initial release
 * Wed Apr 6 2011 Erik van Pienbroek  - 1.0.0-1