README

   1 Tiny C Compiler - C Scripting Everywhere - The Smallest ANSI C compiler
   2 -----------------------------------------------------------------------
   3
   4 Features:
   5 --------
   6
   7 - SMALL! You can compile and execute C code everywhere, for example on
   8   rescue disks (25KB for x86 executable).
   9
  10 - FAST! tcc generates optimized x86 code. No byte code overhead.
  11
  12 - UNLIMITED! Any C dynamic library can be used directly. TCC is
  13   heading torward full ANSI C compliance. TCC can of course compile
  14   itself.
  15
  16 - Compile and execute C source directly. No linking or assembly
  17   necessary. Full C preprocessor included.
  18
  19 - C script supported : just add '#!/usr/local/bin/tcc' at the first
  20   line of your C source, and execute it directly from the command
  21   line.
  22
  23 Documentation:
  24 -------------
  25
  26 1) Installation
  27
  28 ***TCC currently only work on Linux x86***.
  29
  30 Type 'make install' to compile and install tcc in /usr/local and
  31 /usr/local/lib/tcc.
  32
  33 2) Introduction
  34
  35 We assume here that you know ANSI C. Look at the example ex1.c to know
  36 what the programs look like.
  37
  38 The main limitation of tcc is that you cannot use floats.
  39
  40 The include file <tcclib.h> can be used if you want a small basic libc
  41 include support (especially useful for floppy disks). Of course, you
  42 can also use standard headers, although they are slower to compile.
  43
  44 You can begin your C script with '#!/usr/local/bin/tcc' on the first
  45 line and set its execute bits (chmod a+x your_script). Then, you can
  46 launch the C code as a shell or perl script :-) The command line
  47 arguments are put in 'argc' and 'argv' of the main functions, as in
  48 ANSI C.
  49
  50 3) Invokation
  51
  52 '-Idir' : specify an additionnal include path. The
  53 default ones are: /usr/include, /usr/lib/tcc, /usr/local/lib/tcc.
  54
  55 '-Dsym' : define preprocessor symbol 'sym' to 1.
  56
  57 '-lxxx' : dynamically link your program with library
  58 libxxx.so. Standard library paths are checked, including those
  59 specificed with LD_LIBRARY_PATH.
  60
  61 Only one source code can be compiled. If you have multiple source
  62 files, add one which includes all your sources.
  63
  64 4) Examples
  65
  66 ex1.c: simplest example (hello world). Can also be launched directly
  67 as a script: ./ex2.c.
  68
  69 ex2.c: more complicated example: find a number with the four
  70 operations given a list of numbers (benchmark).
  71
  72 ex3.c: compute fibonacci numbers (benchmark).
  73
  74 ex4.c: more complicated: X11 program. Very complicated test in fact
  75 because standard headers are being used ! Currently slow because
  76 parsing does not use hash tables.
  77
  78 ex5.c: 'hello world' with standard glibc headers.
  79
  80 tcc.c: TCC can compile itself. Used to check the code generator.
  81
  82 prog.c: auto test for TCC which tests many subtle possible bugs. Used
  83 when doing 'make test'.
  84
  85 Exact differences with ANSI C:
  86 -----------------------------
  87
  88 1) Preprocessor
  89
  90  - the preprocessor tokens are the same as C. It means that in some
  91   rare cases, preprocessed numbers are not handled exactly as in ANSI
  92   C. This approach has the advantage of being simpler and FAST!
  93
  94  - __LINE__, __FILE__, __DATE__, __TIME__ are currently not handled.
  95
  96  - #line not handled
  97
  98 2) C language
  99
 100 - Parsing: variables cannot be initialized ('int a = 1' or 'int tab[2] =
 101   {1, 2}' not supported).
 102
 103 - Cannot pass struct/union as value. Cannot assign struct/union (use
 104   memcpy instead).
 105
 106 - Types: floating point numbers are not supported.
 107
 108 - (BUG) 'char' and 'short' casts do not truncate correctly.
 109
 110 - 'sizeof' may not work if too complex expression is given.
 111
 112 Supported C extensions:
 113 ----------------------
 114
 115 - 'inline' keyword is ignored.
 116
 117
 118 Technical Description:
 119 ---------------------
 120
 121 This is not my first C compiler (see my 'fbcc' compiler) but it
 122 contains the first C preprocessor I wrote. The project started as a
 123 joke to make the smallest C compiler. Then I expanded it torward ANSI
 124 compliance. This C compiler is particular because each feature was
 125 added while trying to be as simple and compact as possible. For
 126 example, no intermediate structure is used to store code or
 127 expressions.
 128
 129 The TCC code generator directly generates linked binary code. It is
 130 rather unusual these days (see gcc for example which generates text
 131 assembly), but it allows to be very fast and surprisingly not so
 132 complicated.
 133
 134 The TCC code generator is register based. It means that it could even
 135 generate good code for RISC processors. On x86, three temporary
 136 registers are used. When more registers are needed, one register is
 137 flushed in a new local variable.
 138
 139 Constant propagation is done for all operations. Multiplications and
 140 divisions are optimized to shifts when appropriate. Logical operators
 141 are optimized by maintaining a special cache for the processor
 142 flags. &&, || and ! are optimized by maintaining a special 'jmp
 143 target' value. No other jmp optimization is currently performed
 144 because it would require to store the code in a more abstract fashion.
 145
 146 The types and values descriptions are stored in a single 'int'
 147 variable (see VT_xxx constants). It was choosen in the first stages of
 148 development when tcc was much simpler. Now, it may not be the best
 149 solution.
 150
 151 License:
 152 -------
 153
 154 TCC is distributed under the GNU Generic Public License (see COPYING
 155 file).
 156
 157 I accept only patches where you give your copyright explictely to me
 158 to simplify licensing issues.
 159
 160 Fabrice Bellard - Nov 11, 2001.