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