                        LCC 4.2 for RISC OS Release 1
                      
                                20th February 2003

              4.1 and later ported by Peter Naulls (peter@chocky.org)
                    4.0 ported by Reuben Thomas (rrt@sc3d.org)


Peter Naulls is now the maintainer of lcc for RISC OS.  Please do not
contact Reuben regarding it.   See the bottom of this file for changes since
the last version.

lcc is an ANSI C compiler. It is small and fast, though the code it produces
is currently of poor quality. However, because of its speed (about twice as
fast as GNU C with no optimisation) it is useful for development work, when
you spend far more time compiling than running your programs; and because of
its size it should run on computers that cannot accommodate GCC (It
should be possible to use it without virtual memory on machines with 2MB
RAM; possibly even 1MB).

lcc's eventual aim is to be a full free replacment for Norcroft (although it
is not that yet for a variety of reasons), it is also intended to be easy as
possible to use for novices.

Because of the ongoing nature of development, documentation may be lacking
in places.  As such, you should check back often for new releases, which
should be noted on http://www.riscos.info/ which is the new homepage for
lcc for RISC OS.  Make a note of which release number this is.


Conditions


See the files in Docs.Licenses for conditions of use.


Installation


To install lcc, copy the !lcc application out of the distribution
archive to anywhere you like. It can even be installed on a floppy (a squeeze
in 800Kb, more plausible in 1.6Mb.   Do not copy it over an old !lcc - if
you have this, you should delete it.  If you have !CLib, you should also
delete it as it has been deprecated for use with both gcc and lcc.

lcc is also a 32-bit application.  You will need the 32-bit SharedCLibrary
installed to use it.  This version of lcc only outputs 32-bit code;
if you require 26-bit output (and there's really no reason why you should),
then use the older version.

Usage


See the documentation in Docs for how to use lcc and bprint in general usage
(bprint is used for profiling).

By default, lcc will use its SharedCLibrary headers (these are the same
as distributed with GCC), and will link with stubs.  This behaviour is
fine for most uses and need not concern novices.

To compile the example program, run the supplied Obey files in the examples
directory.   You can also do this manually by set CSD to the same level as the
'c' directory. Execute the following command in a taskwindow:

 lcc hello.c -o hello

This should give you a hello world binary.


lcc can also be used with UnixLib. If you do not intend to use it with Unixlib
then you do not need to read this section any further.

This version of lcc requires a 32-bit Unixlib.  This can be obtained from:

http://www.riscos.info/gcc/32bit.html

This is the "unixlibbin.zip" file.

When invoking lcc, use the -Bunix switch. e.g.:

 lcc hello.c -o hello -Bunix


The second example intentionally generates warnings to demonstrate the
use of throwback with the compiler.


The Compiler


If you are interested in the innards, lcc version 3.x is described in detail
in the book `A Retargetable C Compiler: Design and Implementation'
(Addison-Wesley, 1995, ISBN 0-8053-1670-1).  Both the book and the
compiler itself are discussed on lcc's homepage:
http://www.cs.princeton.edu/software/lcc/


Problems and limitations


Lcc has been tested fairly thoroughly: if used to compile itself, this
version then compiles a version identical to itself; but I expect bugs
remain. Please report them to me, not to lcc's authors. A small (less than 10
lines) program demonstrating the bug would be much appreciated.

Lcc is incompatible with Acorn C in two areas: first, it does not widen
float arguments to double before passing them to a function in which they
are declared float, and secondly it does not return some one-word structures
in the same way. In practice this isn't a problem, as neither difference
affects the SharedCLibrary, but it is something to be careful of when
linking to other libraries or code.

The only debugging information provided by the -g flag is function names in
stack backtraces.

If you get error messages about "overflow in floating constant 'x'", it might
be because of a bug in gcc which compiles floating-point constants
incorrectly. I have hand-patched this in the assembler source, but if I've
recompiled lcc without doing this by mistake then the bug will have crept
back in. The tell-tale sign is to try compiling a program that just prints
FLT_MAX. This should not cause an overflow message.

I've not tested bprint and the profiling flags. I'd appreciate any feedback
on how well they work, if at all. I suspect that all I'm likely to do at the
moment is to add a warning notice rather than fixing them.

Source files must have names of the form "foo.c" or "c.foo", and preferably
be passed to LCC as "foo.c".


Acknowledgments (from Reuben Thomas)


The authors of lcc, David Hanson and Chris Fraser, were most helpful while I
was porting it, explaining difficulties and putting up with questions that
were actually answered in their book. I recommend the book (see above) to
anyone interested in how C compilers really work.

Nick Burrett, the maintainer of RISC OS GCC, kindly allowed me to use gcc's
interface to drlink, ld, and his clib stubs library, as well as providing
helpful advice on APCS.

Dave Daniels, author of Drlink, kindly allowed me to distribute it with lcc.

Darren Salt and Nick Burret, the maintainers of as, kindly allowed me to
distribute it with lcc.

Dominic Symes, Tim Tyler and the other authors of Zap continue to provide
the most comfortable programming environment I have yet used on the Acorn or
any other machine.


History


4.0

 - Initial Release by Reuben Thomas


4.1

 (Release 1)
 - New version ported by Peter Naulls.  For the main compiler Changes
   see http://www.cs.princeton.edu/software/lcc/pkg/LOG
 - Documentation updated
 - !Clib removed, instead !lcc contains libscl within itself like !gcc
 - Default output filename is now "!RunImage" instead of "a"
 - Some changes picked up from Andrew Birkett's StrongARM Linux backend
   for 4.1 port.   My eventual aim is to have a unified RISC OS/ARM Linux
   backend so that both platforms benefit from improvements in ARM
   generation.
 - Temporary rearrangment switches to use Unixlib. 


4.1 beta 9

 (Release 1)
 - Brought up to date with most recent LCC developments.  Despite the
   version number, this is more recent than 4.1.


4.1 beta 9

 (Release 2)
 - Fixed bug in ld sometimes leaving temporary files in WimpScrap
 - Add temporary work around for filename translation in libscl which
   would prevent lcc from working on many setups.
 - Rewrote !Boot to remove deprecated items.
 - Changed some paths to ensure lcc binaries only will be used.
 - Added some example programs with build files.


4.2
 - Latest version ported.
 - Converted the compiler and its output to 32-bit
 - Added throwback (thanks to Andrew Sidwell)



