Release notes for the second official PGCC release (v2.90.23 based of egcs 1.0.1)


0) Intro and general notes

Welcome to the new and totally rewritten readme file for PGCC for DJGPP.  
I tried to include more relevant information and scratch the commentary.


This archive contains the following files

bin\gcc.exe      - Compiler Invoker 
bin\cpp.exe      - The GNU Pre-processor
bin\cc1.exe      - The Pentium Optimizing GNU C parser
lib\specs        - Specs file for the compilation process
lib\libgcc.a     - The core compiler library files 
readme.pcg       - This file
faq\pgcc.faq     - DJGPP specific Frequently asked questions
pcg_read.old     - The old reame file that covered all of the snapshots before v1.


The additional C++ archive contains

\bin\cc1plus.exe     - The Pentium Optimizing GNU C++ parser
\bin\gxx.exe         - Optional Replacement Front end for C++ compilation
\lib\libstdcx.a      - C++ Library
\lib\libio.a         - C++ Library
\lib\libiostr.a      - C++ Library
\lib\libibert.a      - Library, probably not used by anything but included anyway
\include\math.h      - Fix struct exception problem
\include\libm\math.h - Fix struct exception problem

What to expect - 

PGCC typically produces code 5-25% faster then GCC 2.7.2 for Pentium and Pentium Pro machines.
PGCC also produces faster code than both GCC 2.8 and egcs 1.0. 
It should also show improvement for Cyrix and AMD machines as well.
It is not a miracle worker however.  Don't substitute this for a good algorithm.
10-15% increases seem somewhat typical.  In general just compile with -O6.



I) Installation Notes 


1) You must have a fully working DJGPP environment before attempting to 
install PGCC.  You can install a newer version of PGCC over an existing PGCC
installation as well.  If you do not have DJGPP installed go to the following
url to see what you need 

http://www.delorie.com/djgpp/zip-picker.html

Supported versions of DJGPP are the following.  

DJDEV 2.01 or later 
binutils 2.7 or later

According to the egcs release notes, if you want exception handling to work
on a x86 target (that DJGPP), then you MUST use binutils 2.8.1 or later.

PGCC can work with some older versions if you really want it to.  See notes below
for how to do that.  I would highly recommend that you upgrade before attempting
to install PGCC over an older version though.

2) Simple unzip the base (and any additional) archive into your DJDIR.  Be sure
to preserve directory information when you do this.  The main pgcc files
will extract into $(DJDIR)/bin and S(DJDIR)/lib.

3) Stack Alignment Fixes.  If you are using DJDEV 2.01 then you must 
do the following (this does not have to be done every time you get a 
new pgcc.  If you have done this previously that is OK).

In $(DJDIR)\src\libc\crt0\crt1.c

change the last line of  function __crt1_startup from 

exit(main(...)); 

to the following inline assembly code

asm("
   andl $0xFFFFFFF8,%%esp
   pushl %%eax
   pushl %0   
   pushl %1
   pushl %2
   call _main
   pushl %%eax
   call _exit
  " :: "m" (environ), "m" (__crt0_argv), "m" (__crt0_argc));

Just compile it and use ar to update the one in DJDIR\lib\libc.a                     

gcc -O6 -c crt1.c
ar rv $(DJDIR)\lib\libc.a crt1.o

If you are using DJDEV 2.02 Alpha from 01/98 or later the stack is already aligned
properly in crt0.s.  You do not need to make a source level change.  You 
do still need to recompile crt1.c and then replace the libc.a version as noted above.


4) Thats it.  Just recompile your code with -O6 or -O7 specified instead of 
"-O3 -m486" or whatever you had been using.  Some other things to use are 
-gstabs instead of -g for debugging info (its much better, although it only 
works with gdb).  



II) C++ Installation Notes 


1) The gxx.exe that comes with pg++ is completely different than the 
gxx.exe that comes with djgpp.  You can actually still use the original
gxx.exe if you want, as the optimizing changes come from the underlying
cc1plus.exe.  If you want to use the new gxx.exe try the following.

Copy the [gcc] section in your djgpp.env to a new section and call it [gxx].  

2) C++ comes with a replacement math.h to work around the struct exception 
problem.  It should be identical to the original djgpp version in 
every other way.

Specifically 

struct exception {

is changed to 

#ifdef __cplusplus
#define exception __math_exception
#endif
struct exception {
#ifdef __cplusplus
#undef exception
#endif

Since exception is a special work in C++.  This is the DJDEV 2.01 math.h.  If 
you are using a 2.02 alpha or later you may need to manually fix 
math.h (or it could already be fixed).

3) The C++ support in gcc has changed substantially since 2.7.2.  I am not a C++
user and I do not know the nature of all of the changes.  I do know that templates
are supposed to be better supported, as well as RTTI.  Also exception handling is
improved (and is now enabled by default, -fno-exceptions turns it off).  I have 
provided what I hope is all the necessary libs.

libio.a
libstdcx.a (libstdc++.a in unix)
libiostr.a (libiostream in unix)
libibert.a (libiberty.a in unix, I don't this this is needed, or even a c++ file
	                         but I'm including it anyway)

4) I do not include a new libgpp.a.  My understanding is that this should not
be needed anymore.  I also do not include the collect2 front end that 
aides in template repository.  It relies on fork to work and dj's posix support
does not include fork currently.



III) Changes since version 2.90.21 egcs 1.0


The specs file now selects libc.a even if profiling is specified on the command line.
This way you don't have to have a special profiling libc present (this is 
compatible with the original dj 2.01 environment)

Hopefully I will rememeber to increase the stack size in cc1.exe and cc1plus.exe (I 
default them to 4MB now). I inadvertently left them at 256K in the v1 release.

Numerous bugfixes went into egcs 1.0.1 and were picked up

I redid this readme file and added a DJGPP specific FAQ.

-mstack-align-double is enabled by default.  This was in the last release
also but I didn't notice and didn't change the readme to reflect it.

gxx.exe now looks for libstdcx.a instead of libstdc++.a



IV) Known Bugs  


1)  It used to be that if you did

gcc -S -o - foo.c 

That gcc would dump the assembly to stdout.  Now, however gcc creates a file
called '-.exe'.  I will investigate the problem as time permits.  Just do 
an edit on the file and you will see the assembly (its not a real exe file, just
a text file).   This became evident after a change I put in to tell the configuration
that DJGPP programs have an executable suffix.  I doubt many people mysides 
myself use the "-o -" option so I have not spent much time on this one.

2)  Either gcov.exe of -fprofile-arcs or -ftest-coverage does not work.  The
combination of '-fprofile-arcs and -ftest-coverage' does generate the expected 
.bb and .bbg files, and running the resulting executable does generate a .da file. 
Upon analysis by gcov.exe though gcov crashes.  I do not know if this is a bug
in gcov or in the output of the block data yet.  I am not distributing gcov.exe in 
the base kit until I get this fixed.

2) Collect2.exe does not work and is not distributed.



V) Requests for Help


1) Three times now, since I have been releasing pgcc, I have run into the following problem.  
After rebuilding djgpp/src (libc and the like), all of my programs crash instantly on startup.
This is a problem because things like symify are built in src, and it crashes too.  Anyway, if I 
unzip a good symify and look at the backtrace on a hello world program I get the following 

_malloc+192

Thats it.  Sometimes something else equally unbelievable.  
Also, programs run file when run under a debugger (gdb), from bash, on some other computers,
or when spawned from another program (like make).  I don't know if this is related to the 
notorious emacs environmental variable bug or not.  My guess is yer.  
Its just really annoying.  If this is happening
to anyone else out there please let me know.  Or if you are troubleshooting something like
this let me know and I will give you any info I can.  For me, if I re-extract the djdev kit, blow
away the src dir, re-extract the lib sources, and rebuild things work OK.

2) If anybody wants to test the future C++ packages before they come 
out please contactly me directly.  They are going out 'as is' right now.



VI) More info on Supported Versions


I have heard that binutils 2.8.x is slightly slower that 2.7.  If you are 
a total speed freak then maybe 2.7 is the way to go.  The specs file
is targetted for 2.7 users (since they need a link script specified), but should
work with 2.8.x binutils (I use binutils 2.8.1 personally).
Binutils 2.6.3 and earlier do not support the .p2align directive that pgcc emits.  
If you really want to get this to work you could use a hex editor to change 
cc1.exe to use .align instead of .p2align.  This is not recommended of course, 
but should work.  The specs file assumes a DJDEV 2.01 kit.  If you are using 2.00 
then you will need to change the specs file to use the old linker script (change djgpp.djl
to be djgpp.lnk instead).  Do not even ask if this will work on DJ 1.x installs, it won't.



VII) How to recompile common packages


1) Allegro

Allegro is very easy.  Snapshots from October 1997 and later and v3 have support for PGCC.  
Just check the top of the makefile.
You may want to check the pcg homepage or this readme to see what optimization options
are currently recommended.  They can fluctuate.  The default settings allegro uses 
should be pretty good and safe though.

Allegro 2.2- Allegro has the sign compare problem.  To get allegro to recompile
change the makefile so that the optimization level is -O6 (also, get rid of
any other options like -m486 if present), and add -Wno-sign-compare after
-Wall.  Thats it, this one is pretty easy.


2) Libc, libm, ...

I will probably be providing a pre-compiled libc soon.  In the meantime here is
how to build 2.01.

Libc itself isn't that bad but some of the 
other packages that come with it (libm, debuggers) are.  Eli Z (FAQ maintainer)
has mentioned that Libc is not be LFN safe.  It should be possible to just set LFN=no 
and get things to work without doing the file renaming I mention below ( I haven't tested
this).

Edit $(DJDIR)\src\gcc.opt to change the optimization level to -O6, and add 
lines for -Wno-sing-compare and -Wno-implicit at the end of the file.  
I also found that make would often times crap out on assembly files.  I 
just did a 'rename *.s *.S' and that took care of it for me (this should not 
be needed if LFN is N).

The 2 ...finite.s files have bugs in them so they won't assemble.  Look for

setnel %al

These both need to be changed to 

setneb %al 

for it to work.

I also had a problem with stuff including math_private.h when my file was
math_pri.h (another LFN problem).  Renaming math_pri.h to math_private.h worked.

Full Screen Debugger - This has a bug in the source code.  In fullscr.c, 
change the line (~399) like this 

xorl %%al,%%al

to be an xorb instead.  Thanks to Bill C for pointing this out.

Mkdoc - The makefile has an explicit call to ld.  
If you just run make you will get undefined references from libc.a, in doprint,
for symbols like ___moddi3 (included from libgcc.a).  
You can add another -lgcc at the end of the ld command line
(from Bill C again) or change it from  

ld ...
stubify ...

To just 

gcc $^ -O..\..\bin\mkdoc.exe

A lot of the auxiliary packages in here have 
the optimization flags specified somewhere other than gcc.opt.  You will
need to poke around and change them if you want.

3) Everything else

This big gotchas are additions to -Wall.  You might try changing -Wall
to be -Wall -Wno-sign-compare -Wno-implicit.  And, of course, changing the 
CFLAGS to use -O6 instead of -O2 or whatever.



VIII) Where to get help  

1) Make sure that you have read this entire readme file, as well as the DJGPP
FAQ, the PGCC DJGPP FAQ, and the PGCC FAQ (on goof), and that your 
problem is not covered there.

2) Do not bother the PCG people with configuration questions or problems.  
They are not DJGPP users (or even DOS users).  They develop on Linux.  That is why I 
am providing these pre-compiled binaries.  If there is a configuration problem, 
and it is specifically related to PGCC (I.E. you had a working DJGPP installing 
and after installing pgcc its broken) then contact me directly. 

My E-Mail is 

andrewc@rosemail.rose.hp.com

I no longer subscribe to the DJGPP mailing list, but I do read the newsgroup frequently,
so any messages sent there should get seen by me (use your judgment as to whether to send 
me private mail or to the DJ list).  Just put PGCC in the subject line and I'll see it.  
I also subscribe to the Beastium list (for pgcc) as well.  My news server is not 100%
reliable so if you want to make sure I see it send a copy to my email.

3) Reporting Bugs -

Always include the exact version of pgcc you are using (gcc -v).  Most bug reports
say 'I have the latest pgcc',  sometimes on the day when I put up a new release.  
Is it the new one or the old one?  Put the version number there so I know for sure.

What if the compiler produces bad code?  Or what if it hangs completely while compiling?
This is something the PCG guys are probably interested in.  You can make things 
easier by doing some work upfront.  First, what to do with a compile hang.  Try increasing
the stack size of cc1.exe (run `stubedit cc1.exe` and follow the onscreen instructions).  
The default size is now 4MB.  Keep increasing values (as memory 
permits) to 8MB and then 16MB.  Marc has seen an all time high stack usage of 40MB! 
If this doesn't correct the problem then try the following.
Compile with the -v option and with the very useful though undocumented -Q option (thanks Eli).  
-Q tells gcc to print out each function as it gets compiled.  You should
be able to tell what function is killing the compiler now.  Once you know this, strip out
all other functions in this code file (you may need to add dummy externs for functions 
you delete).  Now, compile with the -E option (stop after running cpp).  This should 
give you a .i file which is not dependent on any include files to be compiled.  
Send this off to the pcg mailing list.  If you get bad code, try the following.  
Try to isolate things down to the function again, and then send the assembly code 
(output of gcc -S), and the pre-processed C code, as well as the command invokation.

4) Feel free to communicate with me directly.  Also, you can ask for optimization
tips or help with small sections of code if you would like (I also answer all
optimization questions I see on djgpp news list).  There are some guidelines you
can follow to make sure you get the help you want.

a) Keep things small.  I'm much more likely to work on something if you have already
isolated the performance problem down to a function and just send me a simple
pre-processed file that I can recompile and run on my own.  Telling me 'package so
and so available at simtel at 20MB runs slower with pgcc, help please' is not
likely to get my attention.  This would be ideal 'I have profiled my
code and found that the following function (attached as a self-contained 1K file)
runs slower at -O6 than -O2.  I have tried to understand the assembly output but
have been unable to determine why it is slower'.  Also, try to put things 
into english if at all possible.  Spanish (or similar) is OK.  German and French
are pretty iffy.  Anything else, no chance.


IX) Release History

010298 - Egcs 1.01 second official release

120297 - Egcs 1.0 official release 

