Merge branch 'pthreads' of git://repo.or.cz/msysgit into devel

[msysgit.git] / mingw / README-gcc-tdm.txt

===== TDM's Experimental GCC/MinGW32 Builds =====\r
\r
NOTICE:\r
TDM-GCC is an unofficial replacement for the official GCC binaries distributed\r
by the MinGW project; please note the following caveats:\r
 * TDM-GCC is not formally affiliated with or endorsed by the MinGW project\r
    (although several MinGW team members make use of it)\r
 * No level of support for TDM-GCC is in any way guaranteed (although a best\r
    effor is made to fix bugs as they are found or forward them to GCC Bugzilla)\r
\r
BUGS:\r
If you encounter a problem while using a TDM-GCC build that isn't present in a\r
previous MinGW or TDM release, you are encouraged to submit a helpful bug\r
report. Please see <http://www.tdragon.net/recentgcc/bugs.php> for further\r
instructions.\r
\r
\r
>>>>> INSTALLATION\r
\r
*** TDM/MinGW Installer ***\r
\r
Using the TDM/MinGW installer is highly recommended; it can automatically\r
install TDM-GCC (or the official MinGW GCC) as well as all supplementary MinGW\r
base system packages. The installer uses a standard wizard interface with\r
reasonable defaults.\r
\r
*** Manual Installation ***\r
\r
These binary packages are designed as drop-in replacements for the MinGW\r
project's official gcc packages. When using these packages, you are encouraged\r
to start with a clean slate and install only the MinGW packages which are\r
necessary to you. You'll need the following packages for basic Windows\r
development:\r
 * binutils (binutils-2.19.1-mingw32-bin.tar.gz)\r
 * mingw-runtime (mingwrt-3.15.2-mingw32-dev.tar.gz,\r
     mingwrt-3.15.2-mingw32-dll.tar.gz)\r
 * w32api (w32api-3.13-mingw32-dev.tar.gz)\r
You might also want to install: \r
 * mingw-utils (mingw-utils-0.3.tar.gz)\r
 * mingw32-make (mingw32-make-3.81-20080326-3.tar.gz)\r
 * gdb (gdb-6.8-mingw-3.tar.bz2)\r
You'll need GDB particularly if you want to use an IDE with debugging support.\r
\r
Decide whether to use the SJLJ or DW2 (Dwarf-2) exception model. Then, for the\r
exception model of your choice, download at least the "core" TDM-GCC package,\r
which includes the required base files as well as support for the C language.\r
You can also download any or all of the other TDM-GCC packages, depending on\r
which of GCC's supported languages you'd like to use.\r
\r
Extract the MinGW packages to an empty directory -- typically C:\MinGW. Then,\r
extract the TDM-GCC package(s) and choose to overwrite any duplicate files that\r
may exist. Finally, consider adding the bin directory to your Windows PATH\r
environment variable.\r
\r
\r
>>>>> USAGE NOTES\r
\r
*** Dwarf-2 vs. SJLJ unwinding ***\r
\r
GCC supports two methods of stack frame unwinding: Dwarf-2 (DW2) or SJLJ\r
(setjmp/longjmp). Until recently, only SJLJ has been available for the Windows\r
platform. This affects you, the end user, primarily in programs that throw and\r
catch exceptions. Programs which utilize the DW2 unwind method handle exceptions\r
much more quickly than programs which utilize the SJLJ method. However, the DW2\r
method increases code size by a noticeable amount, and additionally cannot yet\r
unwind (pass exceptions) through "foreign" stack frames: stack frames compiled\r
by another non-DW2-enabled compiler, such as OS DLLs in a Windows callback.\r
\r
This means that you should in general choose the SJLJ version of the TDM-GCC\r
builds unless you know you need faster exception handling and can be certain you\r
will never throw an exception through a foreign stack area.\r
\r
As distributed, the SJLJ and DW2 packages of TDM-GCC can coexist peacefully\r
extracted to the same directory (e.g. any files in common are for all intents\r
and purposes identical), because the driver executables (the ones in the "bin"\r
directory) are suffixed with "-dw2" for the DW2 build, and the libraries and\r
other executables hide in another "-dw2" directory in "lib(exec)/gcc/mingw32".\r
This allows you to use the same single addition to your PATH, and use DW2\r
exceptions only when you need them by calling "gcc-dw2", etc. If you truly want\r
DW2 exceptions as the default when calling "gcc" (from Makefiles or configury\r
systems, for example), you can rename or copy the suffixed executables to their\r
original names.\r
\r
TDM releases from the GCC 4.2 series use the SJLJ unwind method.\r
\r
*** Exceptions and DLLs ***\r
\r
The TDM-2 release of GCC 4.3.0 incorporated experimental builds of libgcc and\r
libstdc++ as DLLs in order to allow exceptions to be thrown out of DLLs. With\r
the more recent releases this has been dropped in favor of a ported version of\r
3.4.5's shared memory patch, because of various problems encountered in the DLL\r
versions. (Once these problems are solved, the DLL versions will be included\r
again.)\r
\r
Therefore, you no longer need to add any additional command-line options to\r
throw exceptions out of a DLL. You should, however, still add "-mthreads" to the\r
command line any time you throw exceptions in a multi-threading context.\r
\r
The ported exceptions/DLLs patch is experimental and has only received limited\r
testing, so please report any bugs you encounter in throwing exceptions that are\r
not present in the official MinGW 3.4.5 release.\r
\r
TDM releases from the GCC 4.2 series cannot yet throw exceptions out of DLLs.\r
\r
*** OpenMP and pthreads-w32 ***\r
\r
The core binary package has been built to allow the use of GCC's "-fopenmp"\r
option for generating parallel code as specified by the OpenMP API. (See\r
<http://gcc.gnu.org/onlinedocs/gcc-4.3.2/gcc/C-Dialect-Options.html#index-fopenmp-109>\r
for details.)\r
\r
The OpenMP support in the TDM-GCC builds has received very little testing; if\r
you find build or packaging problems, please send a bug report (see BUGS above).\r
\r
LibGOMP, GCC's implementation of OpenMP, currently only supports the use of the\r
POSIX Threads (pthreads) api for implementing its threading model. Because the\r
MinGW project itself doesn't distribute a pthreads implementation, the\r
"pthreads-win32" library, available from http://sourceware.org/pthreads-win32/,\r
is included in this distribution. If you aren't familiar with pthreads-win32,\r
please read the file "pthreads-win32-README" for more information, or the\r
documentation available at the website referenced above. pthreads-win32 is\r
distributed under the terms of the LGPL; see "COPYING.lib-gcc-tdm.txt" for\r
details.\r
\r
In order to correctly compile code that utilizes OpenMP/libGOMP, you need to add\r
the "-fopenmp" option at compile time AND link time, and link to libgomp.a and\r
libpthread.a at link time ("-lgomp -lpthread"). By default, libpthread.a links\r
the standard C-cleanup DLL version of pthreads-win32 to your program, which\r
means that you will need to ensure that the file "pthreadGC2.dll" (included in\r
the "bin" subdirectory of this package) can be found by your program. If you\r
plan to distribute a program that relies on pthreads-win32, be sure to\r
understand and comply with the terms of the LGPL (see COPYING.lib-gcc-tdm.txt).\r
\r
"libpthread.a" is included in the "lib/gcc/mingw32/4.3.2[-dw2]" subdirectory of\r
this package along with two other pthreads library files:\r
 - "libpthreadGC2-static.a" provides a static version of the pthreads-win32\r
     library, but it requires some additional non-POSIX-compliant startup code\r
     to be included in your program. See "pthreads-win32-README" for\r
     details.\r
 - "libpthreadGCE2.a" provides a version of the pthreads-win32 library with\r
     a somewhat safer response in the face of unexpected C++ exceptions.\r
     The creators of the pthreads-win32 library recommend, however, that this\r
     version not be used, because code written to rely on this is less portable.\r
\r
*** Warnings and errors ***\r
\r
GCC 4 represents a significant step forward in optimization capabilities, error\r
detection, and standards compliance, and this is more true than ever with the\r
advent of the 4.3 release series. For you, the end user, this will mean that\r
code which used to compile and run without problems will almost certainly\r
exhibit some warnings and maybe even a few errors.\r
\r
These meaningful warnings and errors are a very good thing, as they help the\r
programmer to write safer and more correct code. Unfortunately, there's also a\r
chance you might encounter incorrect warnings or errors, ICE's (internal\r
compiler errors, where the compiler makes a mistake and has to bail out), or\r
even miscompilations (where your code is incorrectly compiled and produces the\r
wrong result).\r
\r
If you encounter an ICE while using a TDM-GCC build, feel free to file a bug\r
report (see BUGS above). With any other unexpected problem, you are urged to\r
work from the assumption that it stems from user error, and ensure that your\r
code is correct and standards-compliant. \r
\r
\r
>>>>> BUGS AND KNOWN ISSUES\r
\r
 * [4.3 series only] Under rare and as-yet-unidentified circumstances, inclusion\r
     of a precompiled header will cause compilation to fail with an error like\r
     "error: calling fdopen: bad file descriptor or file name". It seems only to\r
     happen when the PCH is double-included by both an #include directive and\r
     the -include command-line switch, but this in itself will not trigger the\r
     bug.\r
 * [4.1 and 4.2 series only] Exceptions cannot leave DLLs. Recent TDM\r
     releases from the 4.3 series do not have this problem. It only appears in\r
     previous releases when a function in a DLL called from outside the DLL\r
     throws (or fails to catch) an exception, and results in program termination\r
     at that point.\r
 * [4.2 series only] A miscompilation can occur in very specific situations when\r
     -O2 optimization is enabled, if you pass the address of a local pointer\r
     variable to a function that modifies it. Use "-O2 -fno-strict-aliasing" as\r
     a workaround. This has been fixed as of the 4.3 series. (See\r
     <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=32328>.)\r
\r
As these builds are provided on the same basis as the source releases, and the\r
mingw32 target in GCC tends to receive somewhat less-than-average attention,\r
some bugs are expected. If you encounter a bug that you are certain is in the\r
GCC sources (such as an ICE), or that is due to an issue in the building or\r
packaging process, you are encouraged to report it. Please visit the TDM-GCC\r
Bugs Page at <http://www.tdragon.net/recentgcc/bugs.php> for bug reporting\r
instructions.\r
\r
\r
>>>>> LOCAL FIXES AND CHANGES\r
\r
 - [4.3 series] Includes a patch ported from the official MinGW 3.4.5 release to\r
     propagate exceptions out of DLLs without the need for shared versions of\r
     libgcc and libstdc++.\r
 - [4.3 series] Includes a patch which corrects backslash usage in header paths\r
      and fixes path problems when debugging. (See\r
      http://sourceforge.net/tracker2/?func=detail&aid=2145427&group_id=200665&atid=974439)\r
 - Includes a patch to fix a crash when all temporary directory environment\r
      variables are empty.\r
 - Includes a patch to keep GCC from erroneously using the CWD as the\r
     installation directory.\r
 - Configured with "--enable-fully-dynamic-string", which fixes a bug when\r
     passing empty std::string objects between DLLs and EXEs.\r
\r
[The following patches are only necessary for the 4.2 series and have been\r
applied in the 4.3 sources]\r
\r
 - Includes a patch which fixes GCC bug #27067. The primary reason for including\r
     this patch was to let the wxWidgets GUI library compile successfully\r
     out-of-the-box. (See http://gcc.gnu.org/bugzilla/show_bug.cgi?id=27067)\r
 - Includes a patch to remove a dependency on the runtime for the classic ctype\r
     table, moving it to libstdc++ itself. (See\r
     http://gcc.gnu.org/ml/gcc-patches/2007-07/msg01413.html)\r
 - Includes a patch to fix an ICE when compiling gettext (See\r
     http://gcc.gnu.org/bugzilla/show_bug.cgi?id=29826)\r
\r
\r
>>>>> SOURCE CODE\r
\r
The source code for the TDM-GCC binary releases is available from the TDM-GCC\r
download page on SourceForge:\r
<http://sourceforge.net/project/showfiles.php?group_id=200665>\r
(The most up-to-date link to the download site will always be available at\r
<http://www.tdragon.net/recentgcc/>.\r
\r
The source is distributed in the form of the original ("vanilla") separate\r
source packages as downloaded, plus an additional "TDM Sources" package. The TDM\r
Sources package includes unified diffs of any changes made to the vanilla\r
sources, as well as the set of scripts used to build the binary releases.\r
\r
\r
>>>>> LICENSE\r
\r
The TDM-GCC packages contain binary distributions constituting a work based on\r
GCC, which is licensed under the GPL. For further details, refer to the file\r
"COPYING-gcc-tdm.txt" within the downloaded package. Additionally, TDM-GCC\r
contains binary files constituting works based on libiconv, GMP, MPFR, and\r
pthreads-w32, all of which are licensed under the LGPL; COPYING.lib-gcc-tdm.txt\r
contains a copy of the LGPL.\r
\r
The TDM-GCC distribution is free software; you can redistribute it and/or modify\r
it under the terms of the GNU General Public License as published by the Free\r
Software Foundation; either version 3 of the License, or (at your option) any\r
later version.\r
\r
TDM-GCC is distributed in the hope that it will be useful, but WITHOUT ANY\r
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\r
PARTICULAR PURPOSE. See the GNU General Public License for more details.\r
\r
You should have received a copy of the GNU General Public License along with\r
this program. If not, see <http://www.gnu.org/licenses/>.\r