Fixed URI.
[fedora-mingw.git] / packaging-guidelines.txt
1 = Packaging Guidelines for MinGW Windows cross-compiler =
2
3 = Introduction =
4
5 The Fedora MinGW project's mission is to provide an excellent
6 development environment for Fedora users who wish to cross-compile
7 their programs to run on Windows, minimizing the need to use Windows
8 at all.  In the past developers have had to port and compile all of
9 the libraries and tools they have needed, and this huge effort has
10 happened independently many times over.  We aim to eliminate
11 duplication of work for application developers by providing a range of
12 libraries and development tools which have already been ported to the
13 cross-compiler environment.  This means that developers will not need
14 to recompile the application stack themselves, but can concentrate
15 just on the changes needed to their own application.
16
17 Note that when deciding to contribute a new library to the Fedora
18 MinGW project, it is advisable to start with our example specfile:
19 http://hg.et.redhat.com/misc/fedora-mingw--devel/?fl=7e95a9b24e2d;file=example/mingw32-example.spec
20
21 = Track Fedora native package versions =
22
23 In general terms, MinGW packages which provide cross-compiled versions
24 of packages already natively available in Fedora, should follow the
25 native Fedora package as closely as possible.  This means they should
26 stay at the same version, include all the same patches as the native
27 Fedora package, and be built with the same configuration options.
28
29 The MinGW SIG have written an RPM comparison tool which makes it
30 possible to compare MinGW packages with the Fedora native packages, in
31 order to determine whether versions, patches and configuration are
32 aligned.
33
34 = Follow Fedora policy =
35
36 MinGW packages must follow Fedora policy, except where noted in this
37 document.  MinGW packages go through the same review process, CVS
38 admin process etc as other Fedora packages.
39
40 = Package naming =
41
42 Packages should be named by prefixing the upstream package name
43 with <code>mingw32-</code>
44
45 = Base packages =
46
47 The base packages provide a root filesystem, base libraries, binutils
48 (basic programs like 'strip', 'ld' etc), the compiler (gcc) and the
49 Win32 API.  Packages may need to depend on one or more of these.  In
50 particular, almost any conceivable package should depend on
51 <code>mingw32-filesystem</code> and <code>mingw32-runtime</code>.
52
53 {|
54 | <code>mingw32-filesystem</code> || Core filesystem directory layout, and RPM macros for spec files.  Equivalent to 'filesystem' RPM
55 |-
56 | <code>mingw32-runtime</code> || Base libraries for core MinGW runtime & development environment.  Equivalent to glibc & glibc-devel RPMs
57 |-
58 | <code>mingw32-binutils</code> || Cross-compiled binutils (utilities like 'strip', 'as', 'ld') which understand Windows executables and DLLs.  Equivalent to 'binutils' RPM
59 |-
60 | <code>mingw32-w32api</code> || 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
61 |-
62 | <code>mingw32-gcc</code> || GNU compiler collection.  Compilers for C and C++ which cross-compile to a Windows target.  Equivalent to gcc RPM
63 |}
64
65 = Filesystem layout =
66
67  [root]
68    |
69    +- etc
70    |   |
71    |   +- rpm
72    |       |
73    |       +- macros.mingw32
74    |
75    +- usr
76        |
77        +- bin   - Links to cross compiler toolchain
78        |   |
79        |   +- i686-pc-mingw32-cpp
80        |   +- i686-pc-mingw32-gcc
81        |   +- i686-pc-mingw32-g++
82        |   +- ... etc..
83        |
84        +- lib
85        |   |
86        |   +- rpm
87        |       |
88        |       +- mingw32-defs   - custom helper scripts for auto-requires, binary stripping, etc
89        |       +- mingw32-find-provides.sh - extra DLL names
90        |       +- mingw32-find-requires.sh - discover required DLL names
91        |
92        +- i686-pc-mingw32  - root of mingw toolchain and binaries - see next diagram
93
94
95  /usr/i686-pc-mingw32
96    |
97    +- bin  - Cross compiler toolchain  
98    |   |
99    |   +- cpp
100    |   +- gcc
101    |   +- g++
102    |   +- ... etc ...
103    |
104    +- lib  - Cross compiler toolchain support libraries / files
105    |
106    +- sys-root  - root for cross compiled binaries
107        |
108        +- mingw
109            |
110            +- bin     - cross-compiled binaries & runtime DLL parts
111            +- doc     - documentation
112            +- include - include files for cross compiled libs
113            +- lib     - cross-compiled static libraries & linktime DLL parts
114            |   |
115            |   +- pkgconfig  - pkg-config definitions for libraries
116            |
117            +- share
118                |
119                +- man
120
121 = Filenames of the cross-compilers and binutils =
122
123 The cross-compilers and binutils are Fedora binaries and are therefore
124 placed in <code>%{_bindir}</code> (ie. <code>/usr/bin</code>)
125 according to the FHS and Fedora guidelines.
126
127 The cross-compilers and binutils which generate i686 binaries for Windows are named:
128
129  %{_bindir}/i686-pc-mingw32-gcc
130  %{_bindir}/i686-pc-mingw32-g++
131  %{_bindir}/i686-pc-mingw32-ld
132  %{_bindir}/i686-pc-mingw32-as
133  %{_bindir}/i686-pc-mingw32-strip
134  etc.
135
136 The same binaries are present in
137 <code>%{_prefix}/i686-pc-mingw32/bin</code> without any prefix in the
138 name, ie:
139
140  %{_prefix}/i686-pc-mingw32/bin/gcc
141  %{_prefix}/i686-pc-mingw32/bin/g++
142  %{_prefix}/i686-pc-mingw32/bin/ld
143  %{_prefix}/i686-pc-mingw32/bin/as
144  %{_prefix}/i686-pc-mingw32/bin/strip
145  etc.
146
147 = Naming of the root filesystem =
148
149 The root filesystem contains Windows executables and DLLs and any other Windows-only
150 files.  It is necessary both because we need to store Windows libraries in order to
151 link further libraries which depend on them, and also because MinGW requires a
152 root filesystem location.  The location (for i686 target) is provided by the macro:
153
154  %{_mingw32_sysroot}   %{_prefix}/i686-pc-mingw32/sys-root
155
156 = Standard mingw RPM macros =
157
158 The <code>mingw32-filesystem</code> package provides a number of
159 convenience macros for the cross compiled sysroot directories, and
160 toolchain. It is mandatory to use these macros in all MinGW packages
161 submitted to Fedora.
162
163 == Toolchain macros ==
164
165 The following macros are for the %build and %install section of the spec
166
167 {|
168 | _mingw32_ar   || i686-pc-mingw32-ar || cross compiler 'ar' binary
169 |-
170 | _mingw32_cc   || i686-pc-mingw32-gcc || cross compiler 'gcc' binary
171 |-
172 | _mingw32_cflags       || -O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions --param=ssp-buffer-size=4 ||
173 |-
174 | _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
175 |-
176 | _mingw32_cpp  || i686-pc-mingw32-gcc -E || cross compiler 'cpp' binary
177 |-
178 | _mingw32_host || i686-pc-mingw32  || Host platform for build
179 |-
180 | _mingw32_objdump ||   i686-pc-mingw32-objdump || cross compiler 'objdump' binary
181 |-
182 | _mingw32_ranlib       || i686-pc-mingw32-ranlib || cross compiler 'ranlib' binary
183 |-
184 | _mingw32_strip        || i686-pc-mingw32-strip || cross compiler 'strip' binary 
185 |-
186 | _mingw32_target       || i686-pc-mingw32 || Target platform for build
187 |}
188
189 == Filesystem location macros ==
190
191 The following macros are for use in %build, %install and %files sections of the RPM spec
192
193 {|
194 |_mingw32_bindir        || %{_mingw32_prefix}/bin || Location of Windows executables.
195 |-
196 |_mingw32_datadir       || %{_mingw32_prefix}/share || Shared data used under Windows.
197 |-
198 |_mingw32_docdir        || %{_mingw32_prefix}/share/doc || Documentation.
199 |-
200 |_mingw32_infodir       || %{_mingw32_prefix}/share/info || Info files (see note below).
201 |-
202 |_mingw32_includedir    || %{_mingw32_prefix}/include || Header files used when cross-compiling for Windows.
203 |-
204 |_mingw32_libdir        || %{_mingw32_prefix}/lib || Windows libraries (see sections below).
205 |-
206 |_mingw32_libexecdir || %{_mingw32_prefix}/libexec ||
207 |-
208 |_mingw32_mandir        || %{_mingw32_prefix}/share/man || Man pages (see note below).
209 |-
210 |_mingw32_prefix        || %{_mingw32_sysroot}/mingw || Windows equivalent of %{_prefix}, required by MinGW.
211 |-
212 |_mingw32_sbindir       || %{_mingw32_prefix}/sbin ||
213 |-
214 |_mingw32_sysconfdir    || %{_mingw32_prefix}/etc || Configuration files used when running under Windows.
215 |-
216 |_mingw32_sysroot       || %{_prefix}/i686-pc-mingw32/sys-root || Windows system root.
217 |}
218
219 = Dependencies =
220
221 If a package contains binaries which depend on a DLL provided by
222 another package, these dependencies should be expressed in the form:
223
224  mingw32(foo.dll)
225
226 where <code>foo.dll</code> is the name of the DLL.  The name must be
227 converted to lowercase because Windows binaries contain case
228 insensitive dependencies.
229
230 All packages should depend on <code>mingw32-filesystem</code>.
231
232 Correct dependency generation is done automatically.  Packagers should
233 include these lines in all library packages:
234
235  %define _use_internal_dependency_generator 0
236  %define __find_requires %{_mingw32_findrequires}
237  %define __find_provides %{_mingw32_findprovides}
238
239 All specfiles should BuildRequire at least:
240
241  BuildRequires:  mingw32-filesystem >= minimum-version
242
243 and any other BuildRequires that they need.
244
245 = Build architecture =
246
247 All packages should have:
248
249  BuildArch: noarch
250
251 unless they contain Fedora native executables.
252
253 = Libraries (DLLs) =
254
255 All libraries must be built as DLLs.
256
257 Because of the peculiarity of Windows, DLLs are stored in the
258 <code>%{_mingw32_bindir}</code> directory, along with a control file in
259 the <code>%{_mingw32_libdir}</code> directory.  For example, for a
260 library called <code>foo</code> there would be:
261
262  %{_mingw32_bindir}/foo.dll
263  %{_mingw32_bindir}/foo.def
264  %{_mingw32_libdir}/foo.dll.a
265  %{_mingw32_libdir}/foo.la
266
267 All files are required in those locations in order to link
268 successfully, except that the <code>.def</code> file is not always
269 built by libtool for reasons unknown, and the <code>.dll</code> may
270 contain a version number although not always
271 (eg. <code>foo-0.dll</code>).
272
273 == Do not use %{_mingw32_bindir}/* or %{_mingw32_libdir}/* in %files section ==
274
275 The <code>%files</code> section must list DLLs separately.  Packages
276 must NOT use <code>%{_mingw32_bindir}/*</code> or
277 <code>%{_mingw32_libdir}/*</code>
278
279 The reason for this is that libtool is very fragile and will give up
280 on building a DLL very easily.  Therefore we force the name of the DLL
281 to be listed explicitly in the <code>%files</code> section in order to
282 catch this during RPM builds.
283
284 == Manpages and info files ==
285
286 If manpages or info files are simply duplicates of equivalent
287 documentation found in Fedora native packages, then they should not be
288 packaged in the MinGW package.
289
290 == Static libraries ==
291
292 In accordance with ordinary Fedora policy, static libraries should not
293 be built, and if they are then they should be placed in a
294 <code>-static</code> subpackage.
295
296 The exception is the base package <code>mingw32-w32api</code> which
297 contains static libraries that are required for GCC to create
298 executables.
299
300 == Stripping ==
301
302 Libraries and executables should be stripped.  This is done correctly
303 and automatically if the spec file includes these lines:
304
305  %define __strip %{_mingw32_strip}
306  %define __objdump %{_mingw32_objdump}
307
308 (Note that if __strip and __objdump are not overridden in the specfile
309 then this can sometimes cause Windows binaries to be corrupted).