buildtools/legacy/gcc_distribution/README

This is a package of gcc-2.95.3 and binutils-2.15 for BeOS.
Please consult the file "INSTALL" for info about how to install this package.

This port is based on the work done by Takashi Toyoshima, which in turn is 
based on the official gnupro-releases done by Fred Fish and others at Be. 
Thanks to these guys and thanks to everyone who helped testing this new release!

Lots of patches have been applied to get gcc-2.95.3 working properly on BeOS, 
you can find the gory details in the cvs-log-archives. 



These are the main changes:

 - this gcc-2.95.3 won't crash just because one is using iostreams and/or STL.

 - an improved and less buggy libstdc++.r4.so is included (with new headers).

 - the tool-chain now defaults to B_LOW_PRIORITY, such that you can do other
   things while a large build is running. Thanks to Andrew Bachmann for 
   suggesting this. You can override the default with -priority=<prio>.

 - optimization is much more reliable now (it really is a bad idea to 
   use -O2 or -O3 with older compilers, as the likelihood of things going
   very wrong is high!).
   This port should be more reliable when using -O2 or even -O3, but: YMMV!

 - new html-documentation is included for all tools.
 
 - the gcc-option '-shared' is now working again, '-nostart' is a (BeOS-
   specific) synonym for it.


Bugs/Peculiarities:

 - the default specs no longer include -lnet on R5, so some projects that are
   relying on this implicit linking against libnet.so fail during linking
   stage with messages like 'undefined reference to select' (or similar).
   This can be fixed by explicitly adding -lnet to the build.
   The reason for leaving out -lnet from the specs is that this is the way
   things are done under Dano & Zeta and I'd like to avoid having to provide
   different releases for each platform.
   Anyway, if you really want to get back the original R5 behaviour, just change
   the link 
      /boot/develop/tools/gnupro/lib/gcc-lib/i586-pc-beos/2.95.3-beos-xxx/specs
   such that it points to specs.R5 and the R5-compatible specs should be active.

 - gcc-2.95.3 (rightly) complains about code that calls delete on void*. This
   code did not trigger any complaints with older compilers, but it probably
   did not do what the programmer intended. If the pointer is in fact pointing
   to an object, no destructors will be called, only the memory will be freed.
   If that is the original intention, then the global operator delete should 
   be used instead:
       void cleanup (void* cookie) 
       {
           delete cookie;
       }
   becomes
       void cleanup (void* cookie) 
       {
           ::operator delete cookie;
       }
	If the destructor should be called, you have to cast the void* to the
	appropriate type (or preferably get rid of that void* cruft).

 - the linker goes out of its way to avoid generating relocation entries of
   type R_386_NONE with an offset of 0, as this crashes the dynamic loader
   of BONE/Dan0/Zeta.
	Part of the dynamic loading process is the relocation of several entries 
	inside the binary to its real position in memory. The linker generates the
	neccessary relocation entries, telling the loader for each relocation, what 
	kind of relocation is to be done (type) and where the relocation takes place
	(offset into the binary-section). These relocation entries live in several 
	sections named ".rel."...
	The linker from binutils-2.15 seems to do some more optimization than older 
	linkers, converting unneeded relocation-entries (pointing to sections that 
	were discarded during the link) to the R_386_NONE type, which in fact 
	means: "do nothing". The offset of these relocation entries is set to 0.
		[Sidenote: it would be better to remove this entries altogether, but 
		that could change the size of an already layed-out section, which - 
		according to the binutils maintainers - is difficult, so the free space 
		is not yet reclaimed by ld].
	Now it seems that the newer dynamic loader is a bit peculiar about how to 
	handle these "do nothing" requests: it is perfectly happy to nothing at most 
	offsets, only offset 0 it doesn't like at all, as it then tries to execute 
	code like the following:
		xor eax, eax
		movl (eax), eax
	which, naturally, crashes the machine.
	The solution to this was to leave the original offset of these relocation 
	entries in place, just change the type to R_386_NONE. This hack seems to 
	work for all BeOS dynamic loaders.

 - The Be-compilers had the habit of putting automatically generated functions 
   into each object file that uses them. This behaviour corresponds to what gcc
   calls multiple symbol spaces. For ELF, however, multiple symbol spaces do 
   not make much sense, as all global symbols are automatically being exported
   (i.e. there is only a single symbol space). 
   This version of gcc activates multiple symbol spaces only when optimization 
   is switched off. In optimizing mode, a single symbol space is used, in order
   to yield smaller object files, libraries and apps.
   You can use the new switch -f(no-)multiple-symbol-spaces to force gcc to
   use (or not use) multiple symbol spaces.

 - Every app is now automatically linked against a (new) object file named
   fix_bdirectwin_typeinfo.o
   As a result of the multiple / single symbol space issue, older compilers 
   generate typeinfo-functions in each object file that uses them (via 
   dynamic_cast). 
   As this compiler uses a single symbol space when optimizing, type-info 
   functions are not kept in each object file, but they are taken from the 
   library which "defines" the class that is the target of the dynamic_cast. 
   This works fine for most cases, but the Be-libraries seem to contain a 
   broken version of the BDirectWindow-typeinfo-function.
	The difference here is that older compilers never used this function, as the
	linker always linked to the (object-file-)internal version of this funtion. 
	Gcc-2.95.3 doesn't always generate these, so that the one living inside the 
	Be-libraries is being used, which in turn leads to a crash (examples are
	GLTeapot or libSDL.so).
	As a solution to this problem, I have created a new object file, named 
	fix_bdirectwin_typeinfo.o, that contains an implementation of the 
	BDirectWindow-typeinfo-funtion. Every app and library is now linked against
	this file automatically (by means of the specs-file), such that the broken 
	implementation from the libs isn't used.
   You can use the new switch -no-beos-fixes to switch off this fix. This is
   especially useful if you are debugging small test applications and you do
   not want/need the symbols from fix_bdirectwin_typeinfo.o.
	What remains a mystery to me is to what respect this function is broken
	and how it found its way into the libs in the first place...

 - gcc-2.95.3 is a bit more decisive when it comes to the handling of inline 
   assembly operand constraints. The original gcc-2.95.3 contained a bug 
   (or two rather) that resulted in a complaint about a "fixed or forbidden
   register" bx or bp being spilled for an inline asm-clause that requires
   rather a lot of register operands. This bug has been fixed (i.e. bx and
   bp are now only spilled if it is safe to do so), but it's still quite
   probable that inline assembly that compiled and worked for gnupro-000224 
   may not compile instantly with gcc-2.95.3.
   So far I have been able to fix all the inline assembly related problems by 
   specifying other operand constraints, but I wouldn't be surprised if there
   are projects out there for which this won't work.

 - the generation of debugging info has been, and still is, problematic. So
   whenever you encounter weird error messages or other strange behaviour, 
   please try to deactivate debug-info (remove -g from the build). 
   I think it is especially unwise to combine optimization with debug-info 
   (which a lot of opensource projects seem to do by default), as this 
   combination seems to be the least reliable during compilation and the 
   resulting apps aren't useful in the debugger either.

 - I believe 2.95.3 improves upon the other available compilers for BeOS, but
   this does not mean that it is better for all purposes, it is just different!
   So don't be surprised if you encounter internal compiler errors with code 
   that worked for gnupro-000224 or gnupro-991026. Please send me info about 
   any such cases so that I can *try* to work out a solution.

Please send questions & bug-reports to: Oliver Tappe <gcc@hirschkaefer.de>