tinycc/README

Tiny C Compiler - C Scripting Everywhere - The Smallest ANSI C compiler
-----------------------------------------------------------------------

Features:
--------

- SMALL! You can compile and execute C code everywhere, for example on
  rescue disks.

- FAST! tcc generates optimized x86 code. No byte code
  overhead. Compiles, assemble and link about 7 times faster than 'gcc
  -O0'.

- UNLIMITED! Any C dynamic library can be used directly. TCC is
  heading torward full ISOC99 compliance. TCC can of course compile
  itself.

- Compile and execute C source directly. No linking or assembly
  necessary. Full C preprocessor included. 

- C script supported : just add '#!/usr/local/bin/tcc' at the first
  line of your C source, and execute it directly from the command
  line.

Documentation:
-------------

1) Installation

***TCC currently only works on Linux x86***.

Type 'make install' to compile and install tcc in /usr/local/bin and
/usr/local/lib/tcc.

2) Introduction

We assume here that you know ANSI C. Look at the example ex1.c to know
what the programs look like.

The main limitation of tcc is that you cannot use floats. 

The include file <tcclib.h> can be used if you want a small basic libc
include support (especially useful for floppy disks). Of course, you
can also use standard headers, although they are slower to compile.

You can begin your C script with '#!/usr/local/bin/tcc' on the first
line and set its execute bits (chmod a+x your_script). Then, you can
launch the C code as a shell or perl script :-) The command line
arguments are put in 'argc' and 'argv' of the main functions, as in
ANSI C.

3) Invokation

'-Idir' : specify an additionnal include path. The
default ones are: /usr/include, /usr/lib/tcc, /usr/local/lib/tcc.

'-Dsym' : define preprocessor symbol 'sym' to 1.

'-lxxx' : dynamically link your program with library
libxxx.so. Standard library paths are checked, including those
specificed with LD_LIBRARY_PATH.

'-i file' : compile C source 'file' before main C source. With this
command, multiple C files can be compiled and linked together.

4) Examples

ex1.c: simplest example (hello world). Can also be launched directly
as a script: './ex1.c'.

ex2.c: more complicated example: find a number with the four
operations given a list of numbers (benchmark).

ex3.c: compute fibonacci numbers (benchmark).

ex4.c: more complicated: X11 program. Very complicated test in fact
because standard headers are being used !

ex5.c: 'hello world' with standard glibc headers.

tcc.c: TCC can of course compile itself. Used to check the code
generator.

prog.c: auto test for TCC which tests many subtle possible bugs. Used
when doing 'make test'.

5) Full Documentation

Please read tcc-doc.html to have all the features of TCC.

Technical Description:
---------------------

This is not my first C compiler (see my 'fbcc' compiler) but it
contains the first C preprocessor I wrote. The project started as a
joke to make the smallest C compiler. Then I expanded it torward
ISOC99 compliance. This C compiler is particular because each feature
was added while trying to be as simple and compact as possible. For
example, no intermediate structure is used to store code or
expressions.

The TCC code generator directly generates linked binary code. It is
rather unusual these days (see gcc for example which generates text
assembly), but it allows to be very fast and surprisingly not so
complicated.

The TCC code generator is register based. It means that it could even
generate good code for RISC processors. On x86, three temporary
registers are used. When more registers are needed, one register is
flushed in a new local variable.

Constant propagation is done for all operations. Multiplications and
divisions are optimized to shifts when appropriate. Comparison
operators are optimized by maintaining a special cache for the
processor flags. &&, || and ! are optimized by maintaining a special
'jmp target' value. No other jmp optimization is currently performed
because it would require to store the code in a more abstract fashion.

The types and values descriptions are stored in a single 'int'
variable (see VT_xxx constants). It was choosen in the first stages of
development when tcc was much simpler. Now, it may not be the best
solution.

License:
-------

TCC is distributed under the GNU General Public License (see COPYING
file). 

I accept only patches where you give your copyright explicitely to me
to simplify licensing issues.

Fabrice Bellard - Nov 17, 2001.