Archive:PackagingDrafts/MinGW

= Packaging Guidelines for MinGW Windows cross-compiler =

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

= Track Fedora native package versions =

In general terms, MinGW packages which provide cross-compiled versions of packages 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 MinGW packages with the Fedora native packages, in order to determine whether versions, patches and configuration are aligned.

= Follow Fedora policy =

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

= Package naming =

Built packages should be named by prefixing the upstream package name with

Source packages can be named starting with  in order to more easily support a transition to the new MinGW guidelines which mandate that naming. Otherwise two separate package repositories must be set up ("mingw32-foo" and "mingw-foo") with one needing to be marked EOL.

= Base packages =

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

= Filesystem layout =

[root] |  +- etc |  |   |   +- rpm |      |   |       +- macros.mingw32 |  +- usr |      +- bin   - Links to cross compiler toolchain |  |       |   +- i686-pc-mingw32-cpp |  +- i686-pc-mingw32-gcc |  +- i686-pc-mingw32-g++ |  +- ... etc.. |      +- lib |  |       |   +- rpm |      |       |       +- mingw32-defs   - custom helper scripts for auto-requires, binary stripping, etc |      +- mingw32-find-provides.sh - extra DLL names |      +- mingw32-find-requires.sh - discover required DLL names |      +- i686-pc-mingw32  - root of mingw toolchain and binaries - see next diagram

/usr/i686-pc-mingw32 |  +- bin  - Cross compiler toolchain |  |   |   +- cpp |  +- gcc |  +- g++ |  +- ... etc ... |  +- lib  - Cross compiler toolchain support libraries / files |  +- sys-root  - root for cross compiled binaries |      +- mingw |          +- bin     - cross-compiled binaries & runtime DLL parts +- doc    - documentation +- include - include files for cross compiled libs +- lib    - cross-compiled static libraries & linktime DLL parts |  |           |   +- pkgconfig  - pkg-config definitions for libraries |          +- share |              +- man

= Filenames of the cross-compilers and binutils =

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

The cross-compilers and binutils which generate i686 binaries for Windows are named:

%{_bindir}/i686-pc-mingw32-gcc %{_bindir}/i686-pc-mingw32-g++ %{_bindir}/i686-pc-mingw32-ld %{_bindir}/i686-pc-mingw32-as %{_bindir}/i686-pc-mingw32-strip etc.

The same binaries are present in without any prefix in the name, ie:

%{_prefix}/i686-pc-mingw32/bin/gcc %{_prefix}/i686-pc-mingw32/bin/g++ %{_prefix}/i686-pc-mingw32/bin/ld %{_prefix}/i686-pc-mingw32/bin/as %{_prefix}/i686-pc-mingw32/bin/strip etc.

= 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 i686 target) is provided by the macro:

%{_mingw32_sysroot}  %{_prefix}/i686-pc-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 packages submitted to Fedora.

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

Filesystem location macros
The following macros are for use in %build, %install and %files sections of the RPM spec

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

All packages should depend on.

Correct dependency generation is done automatically when using mingw32-filesystem >= 68 which is available in Fedora 15 and above.

When a package also needs to be made available for RHEL-5 or RHEL-6 then packagers should include these lines in their packages:

%global _use_internal_dependency_generator 0 %global __find_requires %{_mingw32_findrequires} %global __find_provides %{_mingw32_findprovides}

All specfiles should BuildRequire at least:

BuildRequires: mingw32-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

All files are required in those locations in order to link successfully, except that the  may contain a version number although not always (eg. ).

Some packages also install a  file in %{_mingw32_libdir}. Such files can usually be deleted as they only contain information which is needed to generate the  file in question and serve no purpose for packages which want to link against these .dll files.

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.

Static libraries
In accordance with ordinary Fedora policy, static libraries should not be built, and if they are then they should be placed in a subpackage.

The exception is the base package  which contains static libraries that are required for GCC to create executables.

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

%global __strip %{_mingw32_strip} %global __objdump %{_mingw32_objdump}

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

Example Specfile
%global __strip %{_mingw32_strip} %global __objdump %{_mingw32_objdump} %define __debug_install_post %{_mingw32_debug_install_post}

Name:          mingw-example Version:       1.2.3 Release:       1%{?dist} Summary:

License:       LGPLv2+ Group:         Development/Libraries URL: Source0:

BuildArch:     noarch

BuildRequires: mingw32-filesystem >= 68 BuildRequires: mingw32-gcc BuildRequires: mingw32-binutils
 * 1) Any additional BuildRequires.

%description
 * 1) description

%package -n mingw32-example Summary: %description -n mingw32-example
 * 1) description

%{?_mingw32_debug_package}

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

%build %{_mingw32_configure} make %{?_smp_mflags}

%install make DESTDIR=$RPM_BUILD_ROOT install

rm $RPM_BUILD_ROOT%{_mingw32_libdir}/libfoo.a
 * 1) Remove static libraries but DON'T remove *.dll.a files.

%files -n mingw32-example %doc COPYING %{_mingw32_bindir}/foo.dll %{_mingw32_libdir}/foo.dll.a
 * 1) etc.

%changelog - Initial RPM release.
 * Wed Sep 10 2008 Richard W.M. Jones  - 1.2.3-1