From: Richard W.M. Jones <"Richard W.M. Jones "> Date: Tue, 23 Sep 2008 18:15:37 +0000 (+0100) Subject: Packaging guidelines, renamed example package. X-Git-Url: http://git.annexia.org/?p=fedora-mingw.git;a=commitdiff_plain;h=52784ea95fea7c0fc96472a5ec80638c6f031b1c Packaging guidelines, renamed example package. --- diff --git a/example/mingw-example.spec b/example/mingw32-example.spec similarity index 62% rename from example/mingw-example.spec rename to example/mingw32-example.spec index 3a1c5d5..8b04aa0 100644 --- a/example/mingw-example.spec +++ b/example/mingw32-example.spec @@ -1,10 +1,10 @@ -%define __strip %{_mingw_strip} -%define __objdump %{_mingw_objdump} +%define __strip %{_mingw32_strip} +%define __objdump %{_mingw32_objdump} %define _use_internal_dependency_generator 0 -%define __find_requires %{_mingw_findrequires} -%define __find_provides %{_mingw_findprovides} +%define __find_requires %{_mingw32_findrequires} +%define __find_provides %{_mingw32_findprovides} -Name: mingw-example +Name: mingw32-example Version: 1.2.3 Release: 1%{?dist} Summary: @@ -17,9 +17,9 @@ BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n) BuildArch: noarch -BuildRequires: mingw-filesystem >= 23 -BuildRequires: mingw-gcc -BuildRequires: mingw-binutils +BuildRequires: mingw32-filesystem >= 23 +BuildRequires: mingw32-gcc +BuildRequires: mingw32-binutils # Any additional BuildRequires. @@ -32,7 +32,7 @@ BuildRequires: mingw-binutils %build -%{_mingw_configure} +%{_mingw32_configure} make @@ -41,7 +41,7 @@ rm -rf $RPM_BUILD_ROOT make DESTDIR=$RPM_BUILD_ROOT install # Remove static libraries but DON'T remove *.dll.a files. -rm $RPM_BUILD_ROOT%{mingw_libdir}/libfoo.a +rm $RPM_BUILD_ROOT%{mingw32_libdir}/libfoo.a %clean @@ -50,8 +50,8 @@ rm -rf $RPM_BUILD_ROOT %files %defattr(-,root,root) -%{_mingw_bindir}/foo.dll -%{_mingw_libdir}/foo.dll.a +%{_mingw32_bindir}/foo.dll +%{_mingw32_libdir}/foo.dll.a # etc. diff --git a/packaging-guidelines.txt b/packaging-guidelines.txt new file mode 100644 index 0000000..b667432 --- /dev/null +++ b/packaging-guidelines.txt @@ -0,0 +1,309 @@ += 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. + +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 mingw32- + += 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 +mingw32-filesystem and mingw32-runtime. + +{| +| mingw32-filesystem || Core filesystem directory layout, and RPM macros for spec files. Equivalent to 'filesystem' RPM +|- +| mingw32-runtime || Base libraries for core MinGW runtime & development environment. Equivalent to glibc & glibc-devel RPMs +|- +| mingw32-binutils || Cross-compiled binutils (utilities like 'strip', 'as', 'ld') which understand Windows executables and DLLs. Equivalent to 'binutils' RPM +|- +| mingw32-w32api || Win32 API. A [http://www.mingw.org/MinGWiki/index.php/w32api 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 +|- +| mingw32-gcc || GNU compiler collection. Compilers for C and C++ which cross-compile to a Windows target. Equivalent to gcc RPM +|} + += 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 %{_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. + += 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 mingw32-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 + +{| +| _mingw32_ar || i686-pc-mingw32-ar || cross compiler 'ar' binary +|- +| _mingw32_cc || i686-pc-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-pc-mingw32-gcc -E || cross compiler 'cpp' binary +|- +| _mingw32_host || i686-pc-mingw32 || Host platform for build +|- +| _mingw32_objdump || i686-pc-mingw32-objdump || cross compiler 'objdump' binary +|- +| _mingw32_ranlib || i686-pc-mingw32-ranlib || cross compiler 'ranlib' binary +|- +| _mingw32_strip || i686-pc-mingw32-strip || cross compiler 'strip' binary +|- +| _mingw32_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 + +{| +|_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: + + %define _use_internal_dependency_generator 0 + %define __find_requires %{_mingw32_findrequires} + %define __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: + + %define __strip %{_mingw32_strip} + %define __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).