Revision as of 12:30, 30 January 2011

Packaging Guidelines for cross compiler framework

Based on the MinGW guidelines
These draft guidelines are based on the MinGW guidelines and will obsolete them

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.

As of Fedora 15 a set of RPM macros and packages have been introduced which help packagers compile binaries for multiple targets. Initially, the targets Win32 and Win64 will be supported. However support for other targets (such as Mac OS X) will become easy to implement.

Note that when deciding to contribute a new cross compiled library to the Fedora project, it is advisable to start with our example specfile: http://hg.et.redhat.com/misc/fedora-mingw--devel/?fl=7e95a9b24e2d;file=example/mingw32-example.spec

Track Fedora native package versions

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

Follow Fedora policy

Cross compiled 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

Packages should be named by prefixing the upstream package name with cross-

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 any conceivable package should depend on cross-filesystem and cross-gcc.

`cross-filesystem`	Core filesystem directory layout, and RPM macros for spec files. Equivalent to 'filesystem' RPM
`cross-binutils`	Cross-compiled binutils (utilities like 'strip', 'as', 'ld') which understand Windows executables and DLLs. Equivalent to 'binutils' RPM
`mingw32-gcc`	GNU compiler collection. Compilers for C and C++ which cross-compile to a Windows target. Equivalent to gcc RPM
`mingw-crt`	Base libraries for core MinGW runtime & development environment. Equivalent to 'glibc' RPM
`mingw-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

Filesystem layout

[root]
  |
  +- etc
  |   |
  |   +- rpm
  |       |
  |       +- macros.cross
  |       +- macros.mingw32
  |       +- macros.mingw64
  |
  +- usr
      |
      +- bin   - Links to 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
      |       |
      |       +- cross-find-debuginfo.sh - extract debug information from Win32 and Win64 binaries
      |       +- cross-find-lang.sh - generates per-target file lists containing translations
      |       +- cross-find-provides.sh - extra DLL names
      |       +- cross-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 binaries
      |
      +- mingw
          |
          +- bin     - cross-compiled binaries & runtime DLL parts
          +- etc     - configuration files
          +- 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 %{_bindir} (ie. /usr/bin) according to the FHS and Fedora guidelines.

The 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 %{_prefix}/i686-w64-mingw32/bin 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 cross-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 cross compiled packages submitted to Fedora.

Toolchain macros

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

_mingw32_ar	i686-w64-mingw32-ar	cross compiler 'ar' binary
_mingw32_cc	i686-w64-mingw32-gcc	cross compiler 'gcc' binary
_mingw32_cflags	-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions --param=ssp-buffer-size=4
_mingw32_configure	CC="%{_mingw32_cc}" CFLAGS="%{_mingw32_cflags}" ./configure --build=%_build --host=%{_mingw32_host} --target=%{_mingw32_target} --prefix=%{_mingw32_prefix}	standard invocation for autotools 'configure' scripts
_mingw32_cpp	i686-w64-mingw32-gcc -E	cross compiler 'cpp' binary
_mingw32_host	i686-w64-mingw32	Host platform for build
_mingw32_objdump	i686-w64-mingw32-objdump	cross compiler 'objdump' binary
_mingw32_ranlib	i686-w64-mingw32-ranlib	cross compiler 'ranlib' binary
_mingw32_strip	i686-w64-mingw32-strip	cross compiler 'strip' binary
_mingw32_target	i686-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

_mingw32_bindir	%{_mingw32_prefix}/bin	Location of Windows executables.
_mingw32_datadir	%{_mingw32_prefix}/share	Shared data used under Windows.
_mingw32_docdir	%{_mingw32_prefix}/share/doc	Documentation.
_mingw32_infodir	%{_mingw32_prefix}/share/info	Info files (see note below).
_mingw32_includedir	%{_mingw32_prefix}/include	Header files used when cross-compiling for Windows.
_mingw32_libdir	%{_mingw32_prefix}/lib	Windows libraries (see sections below).
_mingw32_libexecdir	%{_mingw32_prefix}/libexec
_mingw32_mandir	%{_mingw32_prefix}/share/man	Man pages (see note below).
_mingw32_prefix	%{_mingw32_sysroot}/mingw	Windows equivalent of %{_prefix}, required by MinGW.
_mingw32_sbindir	%{_mingw32_prefix}/sbin
_mingw32_sysconfdir	%{_mingw32_prefix}/etc	Configuration files used when running under Windows.
_mingw32_sysroot	%{_prefix}/i686-pc-mingw32/sys-root	Windows system root.

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 foo.dll 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 mingw32-filesystem.

Correct dependency generation is done automatically. Packagers should include these lines in all library 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 %{_mingw32_bindir} directory, along with a control file in the %{_mingw32_libdir} directory. For example, for a library called foo there would be:

%{_mingw32_bindir}/foo.dll
%{_mingw32_bindir}/foo.def
%{_mingw32_libdir}/foo.dll.a
%{_mingw32_libdir}/foo.la

All files are required in those locations in order to link successfully, except that the .def file is not always built by libtool for reasons unknown, and the .dll may contain a version number although not always (eg. foo-0.dll).

Do not use %{_mingw32_bindir}/* or %{_mingw32_libdir}/* in %files section

The %files section must list DLLs separately. Packages must NOT use %{_mingw32_bindir}/* or %{_mingw32_libdir}/*

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 %files 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 -static subpackage.

The exception is the base package mingw32-w32api 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).

Search

PackagingDrafts/MinGWCrossCompiler: Difference between revisions