Installer: Make IsDirWritable() remove all its temporary dirs / files
[msysgit.git] / mingw / README-gcc-tdm.txt
blob7aa90948f19ee8004b42f2995d8afdaf831c1d7b
1 ===== TDM's Experimental GCC/MinGW32 Builds =====
3 NOTICE:
4 TDM-GCC is an unofficial replacement for the official GCC binaries distributed
5 by the MinGW project; please note the following caveats:
6  * TDM-GCC is not formally affiliated with or endorsed by the MinGW project
7     (although several MinGW team members make use of it)
8  * No level of support for TDM-GCC is in any way guaranteed (although a best
9     effor is made to fix bugs as they are found or forward them to GCC Bugzilla)
11 BUGS:
12 If you encounter a problem while using a TDM-GCC build that isn't present in a
13 previous MinGW or TDM release, you are encouraged to submit a helpful bug
14 report. Please see <http://www.tdragon.net/recentgcc/bugs.php> for further
15 instructions.
18 >>>>> INSTALLATION
20 *** TDM/MinGW Installer ***
22 Using the TDM/MinGW installer is highly recommended; it can automatically
23 install TDM-GCC (or the official MinGW GCC) as well as all supplementary MinGW
24 base system packages. The installer uses a standard wizard interface with
25 reasonable defaults.
27 *** Manual Installation ***
29 These binary packages are designed as drop-in replacements for the MinGW
30 project's official gcc packages. When using these packages, you are encouraged
31 to start with a clean slate and install only the MinGW packages which are
32 necessary to you. You'll need the following packages for basic Windows
33 development:
34  * binutils (binutils-2.19.1-mingw32-bin.tar.gz)
35  * mingw-runtime (mingwrt-3.15.2-mingw32-dev.tar.gz)
36  * w32api (w32api-3.13-mingw32-dev.tar.gz)
37 You might also want to install:
38  * mingw-utils (mingw-utils-0.3.tar.gz)
39  * mingw32-make (mingw32-make-3.81-20080326-3.tar.gz)
40  * gdb (gdb-6.8-mingw-3.tar.bz2)
41 You'll need GDB particularly if you want to use an IDE with debugging support.
43 Decide whether to use the SJLJ or DW2 (Dwarf-2) exception model. Then, for the
44 exception model of your choice, download at least the "core" TDM-GCC package,
45 which includes the required base files as well as support for the C language.
46 You can also download any or all of the other TDM-GCC packages, depending on
47 which of GCC's supported languages you'd like to use.
49 Extract the MinGW packages to an empty directory -- typically C:\MinGW. Then,
50 extract the TDM-GCC package(s) and choose to overwrite any duplicate files that
51 may exist. Finally, consider adding the bin directory to your Windows PATH
52 environment variable.
55 >>>>> USAGE NOTES
57 *** "Graphite" Loop Transformations ***
59 The TDM release of GCC 4.4.0 includes support for GCC 4.4's Graphite loop
60 transformation infrastructure. Because support for these optimizations is
61 currently optional, they are not enabled at any of the -O optimization levels.
62 If you are interested in using them, the relevant options are
63 "-floop-interchange", "-floop-strip-mine", and "-floop-block", and they are
64 documented at
65 <http://gcc.gnu.org/onlinedocs/gcc-4.4.0/gcc/Optimize-Options.html>
67 *** Dwarf-2 vs. SJLJ unwinding ***
69 GCC supports two methods of stack frame unwinding: Dwarf-2 (DW2) or SJLJ
70 (setjmp/longjmp). Until recently, only SJLJ has been available for the Windows
71 platform. This affects you, the end user, primarily in programs that throw and
72 catch exceptions. Programs which utilize the DW2 unwind method handle exceptions
73 much more quickly than programs which utilize the SJLJ method. However, the DW2
74 method increases code size by a noticeable amount, and additionally cannot yet
75 unwind (pass exceptions) through "foreign" stack frames: stack frames compiled
76 by another non-DW2-enabled compiler, such as OS DLLs in a Windows callback.
78 This means that you should in general choose the SJLJ version of the TDM-GCC
79 builds unless you know you need faster exception handling and can be certain you
80 will never throw an exception through a foreign stack area.
82 As distributed, the SJLJ and DW2 packages of TDM-GCC can coexist peacefully
83 extracted to the same directory (e.g. any files in common are for all intents
84 and purposes identical), because the driver executables (the ones in the "bin"
85 directory) are suffixed with "-dw2" for the DW2 build, and the libraries and
86 other executables hide in another "-dw2" directory in "lib(exec)/gcc/mingw32".
87 This allows you to use the same single addition to your PATH, and use DW2
88 exceptions only when you need them by calling "gcc-dw2", etc. If you truly want
89 DW2 exceptions as the default when calling "gcc" (from Makefiles or configury
90 systems, for example), you can rename or copy the suffixed executables to their
91 original names.
93 *** Exceptions and DLLs ***
95 The mingw32 port of GCC is gradually moving toward the generally accepted method
96 the rest of the world uses in allowing exceptions to propagate out of shared
97 libraries (DLLs) -- that is, reliance on a third DLL to contain state data
98 for the exception handling system. For any GCC language that supports exceptions
99 (and DLLs), this actually involves two extra DLLs: (1) libgcc_s*.dll, which
100 contains common core data, and (2) a language-specific DLL. You will note that
101 the first phase of this move (libgcc_s*.dll) finally builds correctly
102 out-of-the-box, but NOT THE SECOND PHASE (the language-specific DLLs).
104 Until such time as the language-specific DLLs build correctly, therefore,
105 TDM-GCC will continue to rely on a versioned shared memory region. You do not
106 need any additional command-line options to throw exceptions out of DLLs.
108 If you'd like to try out the new libgcc DLL for other reasons, add
109 "-shared-libgcc" to the command line, but be warned -- it may *break* inter-DLL
110 exceptions.
112 *** OpenMP and pthreads-w32 ***
114 The core binary package has been built to allow the use of GCC's "-fopenmp"
115 option for generating parallel code as specified by the OpenMP API. (See
116 <http://gcc.gnu.org/onlinedocs/gcc-4.4.0/libgomp/> for details.)
118 The OpenMP support in the TDM-GCC builds has received very little testing; if
119 you find build or packaging problems, please send a bug report (see BUGS above).
121 LibGOMP, GCC's implementation of OpenMP, currently only supports the use of the
122 POSIX Threads (pthreads) api for implementing its threading model. Because the
123 MinGW project itself doesn't distribute a pthreads implementation, the
124 "pthreads-win32" library, available from http://sourceware.org/pthreads-win32/,
125 is included in this distribution. If you aren't familiar with pthreads-win32,
126 please read the file "pthreads-win32-README" for more information, or the
127 documentation available at the website referenced above. pthreads-win32 is
128 distributed under the terms of the LGPL; see "COPYING.lib-gcc-tdm.txt" for
129 details.
131 In order to correctly compile code that utilizes OpenMP/libGOMP, you need to add
132 the "-fopenmp" option at compile time AND link time, and link to libgomp.a and
133 libpthread.a at link time ("-lgomp -lpthread"). By default, libpthread.a links
134 the standard C-cleanup DLL version of pthreads-win32 to your program, which
135 means that you will need to ensure that the file "pthreadGC2.dll" (included in
136 the "bin" subdirectory of this package) can be found by your program. If you
137 plan to distribute a program that relies on pthreads-win32, be sure to
138 understand and comply with the terms of the LGPL (see COPYING.lib-gcc-tdm.txt).
140 "libpthread.a" is included in the "lib/gcc/mingw32/4.4.0[-dw2]" subdirectory of
141 this package along with two other pthreads library files:
142  - "libpthreadGC2-static.a" provides a static version of the pthreads-win32
143      library, but it requires some additional non-POSIX-compliant startup code
144      to be included in your program. See "pthreads-win32-README" for
145      details.
146  - "libpthreadGCE2.a" provides a version of the pthreads-win32 library with
147      a somewhat safer response in the face of unexpected C++ exceptions.
148      The creators of the pthreads-win32 library recommend, however, that this
149      version not be used, because code written to rely on this is less portable.
151 *** Warnings and errors ***
153 GCC 4 represents a significant step forward in optimization capabilities, error
154 detection, and standards compliance, and this is more true than ever with the
155 most recent GCC releases. For you, the end user, this will mean that code which
156 compiled and ran without problems on previous GCC releases will almost certainly
157 exhibit some warnings and maybe even a few errors.
159 These meaningful warnings and errors are a very good thing, as they help the
160 programmer to write safer and more correct code. Unfortunately, there's also a
161 chance you might encounter incorrect warnings or errors, ICE's (internal
162 compiler errors, where the compiler makes a mistake and has to bail out), or
163 even miscompilations (where your code is incorrectly compiled and produces the
164 wrong result).
166 If you encounter an ICE while using a TDM-GCC build, feel free to file a bug
167 report (see BUGS above). With any other unexpected problem, you are urged to
168 work from the assumption that it stems from user error, and ensure that your
169 code is correct and standards-compliant. 
172 >>>>> BUGS AND KNOWN ISSUES
174  * Under rare and as-yet-unidentified circumstances, inclusion of a precompiled
175      header will cause compilation to fail with an error like "error: calling
176      fdopen: bad file descriptor or file name". It seems only to happen when the
177      PCH is double-included by both an #include directive and the -include
178      command-line switch, but this in itself will not trigger the bug.
180 As these builds are provided on the same basis as the source releases, and the
181 mingw32 target in GCC tends to receive somewhat less-than-average attention,
182 some bugs are expected. If you encounter a bug that you are certain is in the
183 GCC sources (such as an ICE), or that is due to an issue in the building or
184 packaging process, you are encouraged to report it. Please visit the TDM-GCC
185 Bugs Page at <http://www.tdragon.net/recentgcc/bugs.php> for bug reporting
186 instructions.
189 >>>>> LOCAL FIXES AND CHANGES
191  - Includes a patch ported from the official MinGW 3.4.5 release to propagate
192      exceptions out of DLLs without the need for shared versions of libgcc and
193      libstdc++.
194  - Includes a patch which corrects backslash usage in header paths and fixes
195       path problems when debugging. (See
196       http://sourceforge.net/tracker2/?func=detail&aid=2145427&group_id=200665&atid=974439)
197  - Includes a patch to keep GCC from erroneously using the CWD as the
198      installation directory.
199  - Configured with "--enable-fully-dynamic-string", which fixes a bug when
200      passing empty std::string objects between DLLs and EXEs.
202 [The following patches are only necessary for the 4.3 series and have been
203 applied in the 4.4 sources]
205  - Includes a patch to fix a crash when all temporary directory environment
206      variables are empty.
209 >>>>> SOURCE CODE
211 The source code for the TDM-GCC binary releases is available from the TDM-GCC
212 download page on SourceForge:
213 <http://sourceforge.net/project/showfiles.php?group_id=200665>
214 (The most up-to-date link to the download site will always be available at
215 <http://www.tdragon.net/recentgcc/>.
217 The source is distributed in the form of the original ("vanilla") separate
218 source packages as downloaded, plus an additional "TDM Sources" package. The TDM
219 Sources package includes unified diffs of any changes made to the vanilla
220 sources, as well as the set of scripts used to build the binary releases.
223 >>>>> LICENSE
225 The TDM-GCC packages contain binary distributions constituting a work based on
226 GCC, CLooG, and PPL, all of which are licensed under the GPL. For further
227 details, refer to the file "COPYING-gcc-tdm.txt" within the downloaded package.
228 Additionally, TDM-GCC contains binary files constituting works based on
229 libiconv, GMP, MPFR, and pthreads-w32, all of which are licensed under the LGPL;
230 COPYING.lib-gcc-tdm.txt contains a copy of the LGPL.
232 The TDM-GCC distribution is free software; you can redistribute it and/or modify
233 it under the terms of the GNU General Public License as published by the Free
234 Software Foundation; either version 3 of the License, or (at your option) any
235 later version.
237 TDM-GCC is distributed in the hope that it will be useful, but WITHOUT ANY
238 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
239 PARTICULAR PURPOSE. See the GNU General Public License for more details.
241 You should have received a copy of the GNU General Public License along with
242 this program. If not, see <http://www.gnu.org/licenses/>.