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.

- UNLIMITED! Any C dynamic library can be used directly. TCC is
  heading torwards full ANSI C 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 !

- For adventurers, tcc is conceived to be able to generate code for
  other targets.

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

1) Installation

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

Type 'make install' to compile and install tcc in /usr/local 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 limitations of tcc are 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.

Only one source code can be compiled. If you have multiple source
files, add one which includes all your sources.

4) Examples

ex1.c: simplest example (hello world). Can also be launched directly
as a script: ./ex2.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 ! Currently slow because
parsing does not use hash tables.

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

tcc.c: TCC can 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'.

Exact differences with ANSI C:
-----------------------------

1) Preprocessor

 - the preprocessor tokens are the same as C. It means that in some
  rare cases, preprocessed numbers are not handled exactly as in ANSI
  C. This approach has the advantage of being simpler and FAST!

 - __LINE__, __FILE__, __DATE__, __TIME__ are currently not handled.

 - #line not handled

2) C language

- Parsing: variables cannot be initialized ('int a = 1' or 'int tab[2] =
  {1, 2}' not supported).

- Cannot pass struct/union as value. Cannot assign struct/union (use
  memcpy instead).

- Types: floating point numbers are not supported.

- (BUG) 'char' and 'short' casts do not truncate correctly.

- 'sizeof' may not work if too complex expression is given.

Supported C extensions:
----------------------

- 'inline' keyword is ignored.


License:
-------

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

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

Fabrice Bellard - Nov 11, 2001.