From Fedora Project Wiki

No edit summary
No edit summary
Line 4: Line 4:
for discussion and will be deleted from the final document.
for discussion and will be deleted from the final document.


== Introduction ==
= Introduction =


The Fedora MinGW project's mission is to provide an excellent
The Fedora MinGW project's mission is to provide an excellent
Line 22: Line 22:
http://hg.et.redhat.com/misc/fedora-mingw--devel/?fl=c010b6ca7d68;file=example/mingw-example.spec
http://hg.et.redhat.com/misc/fedora-mingw--devel/?fl=c010b6ca7d68;file=example/mingw-example.spec


== Track Fedora native package versions ==
= Track Fedora native package versions =


In general terms, MinGW packages which provide cross-compiled versions
In general terms, MinGW packages which provide cross-compiled versions
Line 35: Line 35:
aligned.
aligned.


== Follow Fedora policy ==
= Follow Fedora policy =


MinGW packages must follow Fedora policy, except where noted in this
MinGW packages must follow Fedora policy, except where noted in this
Line 41: Line 41:
admin process etc as other Fedora packages.
admin process etc as other Fedora packages.


== Package naming ==
= Package naming =


Packages should be named by prefixing the upstream package name
Packages should be named by prefixing the upstream package name
Line 51: Line 51:
(b) we may want to build 64 bit binaries.
(b) we may want to build 64 bit binaries.


== Base packages ==
= Base packages =


The base packages provide a root filesystem, base libraries, binutils
The base packages provide a root filesystem, base libraries, binutils
Line 74: Line 74:
names as Debian (minus the unnecessary '32' which Debian has in the name).
names as Debian (minus the unnecessary '32' which Debian has in the name).


== Filesystem layout ==
= Filesystem layout =


  [root]
  [root]
Line 129: Line 129:
               +- man
               +- man


== Filenames of the cross-compilers and binutils ==
= Filenames of the cross-compilers and binutils =


The cross-compilers and binutils are Fedora binaries and are therefore
The cross-compilers and binutils are Fedora binaries and are therefore
Line 163: Line 163:
prefix.
prefix.


== Naming of the root filesystem ==
= Naming of the root filesystem =


The root filesystem contains Windows executables and DLLs and any other Windows-only
The root filesystem contains Windows executables and DLLs and any other Windows-only
Line 176: Line 176:
it is still a directory located directly under /usr), and is what MinGW expects.
it is still a directory located directly under /usr), and is what MinGW expects.


== Standard mingw RPM macros ==
= Standard mingw RPM macros =


The <code>mingw-filesystem</code> package provides a number of
The <code>mingw-filesystem</code> package provides a number of
Line 183: Line 183:
submitted to Fedora.
submitted to Fedora.


=== Toolchain macros ===
== Toolchain macros ==


The following macros are for the %build and %install section of the spec
The following macros are for the %build and %install section of the spec
Line 209: Line 209:
|}
|}


=== Filesystem location macros ===
== Filesystem location macros ==


The following macros are for use in %build, %install and %files sections of the RPM spec
The following macros are for use in %build, %install and %files sections of the RPM spec
Line 239: Line 239:
|}
|}


== Dependencies ==
= Dependencies =


If a package contains binaries which depend on a DLL provided by
If a package contains binaries which depend on a DLL provided by
Line 265: Line 265:
and any other BuildRequires that they need.
and any other BuildRequires that they need.


== Build architecture ==
= Build architecture =


All packages should have:
All packages should have:
Line 277: Line 277:
architecture was used to build or host them.
architecture was used to build or host them.


== Libraries (DLLs) ==
= Libraries (DLLs) =


All libraries must be built as DLLs.
All libraries must be built as DLLs.
Line 297: Line 297:
(eg. <code>foo-0.dll</code>).
(eg. <code>foo-0.dll</code>).


=== Do not use %{_mingw_bindir}/* or %{_mingw_libdir}/* in %files section ===
== Do not use %{_mingw_bindir}/* or %{_mingw_libdir}/* in %files section ==


The <code>%files</code> section must list DLLs separately.  Packages
The <code>%files</code> section must list DLLs separately.  Packages
Line 308: Line 308:
this during RPM builds.
this during RPM builds.


=== Manpages and info files ===
== Manpages and info files ==


If manpages or info files are simply duplicates of equivalent
If manpages or info files are simply duplicates of equivalent
Line 314: Line 314:
packaged in the MinGW package.
packaged in the MinGW package.


=== Static libraries ===
== Static libraries ==


In accordance with ordinary Fedora policy, static libraries should not
In accordance with ordinary Fedora policy, static libraries should not
Line 324: Line 324:
executables.
executables.


=== Stripping ===
== Stripping ==


Libraries and executables should be stripped.  This is done correctly
Libraries and executables should be stripped.  This is done correctly

Revision as of 15:03, 21 September 2008

Packaging Guidelines for MinGW Windows cross-compiler

Please note this is a draft. "Rationale" sections are for discussion and will be deleted from the final document.

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.

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

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

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

Rationale Debian name their packages mingw32-*. However I can't see a reason for including '32' in the name, particularly since (a) the upstream package is just called mingw and (b) we may want to build 64 bit binaries.

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 mingw-filesystem and mingw-runtime.

mingw-filesystem Core filesystem directory layout, and RPM macros for spec files. Equivalent to 'filesystem' RPM
mingw-runtime Base libraries for core MinGW runtime & development environment. Equivalent to glibc & glibc-devel RPMs
mingw-binutils Cross-compiled binutils (utilities like 'strip', 'as', 'ld') which understand Windows executables and DLLs. Equivalent to 'binutils' RPM
mingw-w32api Win32 API. A free (public domain) reimplementation of the header files required to link to the Win32 API. No direct equivalent in base Fedora - glibc-devel is closest
mingw-gcc GNU compiler collection. Compilers for C and C++ which cross-compile to a Windows target. Equivalent to gcc RPM

Rationale I've used the same names as the upstream packages, and also the same names as Debian (minus the unnecessary '32' which Debian has in the name).

Filesystem layout

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

Rationale This is the name which autoconf configure scripts expect when they are invoked in cross-compiling mode. The /usr/i686-pc-mingw32/bin directory is required by GCC, otherwise it invokes the wrong assembler and linker. Note that we don't support generating x86-64 Windows binaries (or any other architecture) at the moment, but if we do those will have a different prefix.

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:

%{_mingw_sysroot}   %{_prefix}/i686-pc-mingw/sys-root

Rationale This is what the existing Fedora packages do, and very similar to what Debian is doing (they use a different and inconsistent name, but it is still a directory located directly under /usr), and is what MinGW expects.

Standard mingw RPM macros

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 packages submitted to Fedora.

Toolchain macros

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

_mingw_ar i686-pc-mingw32-ar cross compiler 'ar' binary
_mingw_cc i686-pc-mingw32-gcc cross compiler 'gcc' binary
_mingw_cflags -O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions --param=ssp-buffer-size=4 Rationale: we need to remove the -m64 flag from standard RPM_OPTS_FLAGS
_mingw_configure CC="%{_mingw_cc}" CFLAGS="%{_mingw_cflags}" ./configure --build=%_build --host=%{_mingw_host} --target=%{_mingw_target} --prefix=%{_mingw_prefix} standard invocation for autotools 'configure' scripts
_mingw_cpp i686-pc-mingw32-gcc -E cross compiler 'cpp' binary
_mingw_host i686-pc-mingw32 Host platform for build
_mingw_objdump i686-pc-mingw32-objdump cross compiler 'objdump' binary
_mingw_ranlib i686-pc-mingw32-ranlib cross compiler 'ranlib' binary
_mingw_strip i686-pc-mingw32-strip cross compiler 'strip' binary
_mingw_target i686-pc-mingw32 Target platform for build

Filesystem location macros

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

_mingw_bindir %{_mingw_prefix}/bin Location of Windows executables.
_mingw_datadir %{_mingw_prefix}/share Shared data used under Windows.
_mingw_docdir %{_mingw_prefix}/share/doc Documentation.
_mingw_infodir %{_mingw_prefix}/share/info Info files (see note below).
_mingw_includedir %{_mingw_prefix}/include Header files used when cross-compiling for Windows.
_mingw_libdir %{_mingw_prefix}/lib Windows libraries (see sections below).
_mingw_libexecdir %{_mingw_prefix}/libexec
_mingw_mandir %{_mingw_prefix}/share/man Man pages (see note below).
_mingw_prefix %{_mingw_sysroot}/mingw Windows equivalent of %{_prefix}, required by MinGW.
_mingw_sbindir %{_mingw_prefix}/sbin
_mingw_sysconfdir %{_mingw_prefix}/etc Configuration files used when running under Windows.
_mingw_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:

mingw(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 mingw-filesystem.

Correct dependency generation is done automatically. Packagers should include these lines in all library packages:

%define _use_internal_dependency_generator 0
%define __find_requires %{_mingw_findrequires}
%define __find_provides %{_mingw_findprovides}

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.

Rationale Windows executables always target 32 bit x86 at present, and so (in theory) should be identical whatever Fedora architecture was used to build or host them.

Libraries (DLLs)

All libraries must be built as DLLs.

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

%{_mingw_bindir}/foo.dll
%{_mingw_bindir}/foo.def
%{_mingw_libdir}/foo.dll.a
%{_mingw_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 %{_mingw_bindir}/* or %{_mingw_libdir}/* in %files section

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

Rationale 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 mingw-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:

%define __strip %{_mingw_strip}
%define __objdump %{_mingw_objdump}

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