mingw/README-gcc-tdm.txt

   1 ===== TDM's Experimental GCC/MinGW32 Builds =====
   2
   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)
  10
  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.
  16
  17
  18 >>>>> INSTALLATION
  19
  20 *** TDM/MinGW Installer ***
  21
  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.
  26
  27 *** Manual Installation ***
  28
  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.
  42
  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.
  48
  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.
  53
  54
  55 >>>>> USAGE NOTES
  56
  57 *** "Graphite" Loop Transformations ***
  58
  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>
  66
  67 *** Dwarf-2 vs. SJLJ unwinding ***
  68
  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.
  77
  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.
  81
  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.
  92
  93 *** Exceptions and DLLs ***
  94
  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).
 103
 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.
 107
 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.
 111
 112 *** OpenMP and pthreads-w32 ***
 113
 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.)
 117
 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).
 120
 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.
 130
 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).
 139
 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.
 150
 151 *** Warnings and errors ***
 152
 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.
 158
 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).
 165
 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.
 170
 171
 172 >>>>> BUGS AND KNOWN ISSUES
 173
 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.
 179
 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.
 187
 188
 189 >>>>> LOCAL FIXES AND CHANGES
 190
 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.
 201
 202 [The following patches are only necessary for the 4.3 series and have been
 203 applied in the 4.4 sources]
 204
 205  - Includes a patch to fix a crash when all temporary directory environment
 206      variables are empty.
 207
 208
 209 >>>>> SOURCE CODE
 210
 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/>.
 216
 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.
 221
 222
 223 >>>>> LICENSE
 224
 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.
 231
 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.
 236
 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.
 240
 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/>.