fixed macro bug and dummy float constant parsing
[tinycc.git] / README
blob67bf04d4f4101a979581e6a2f4b7aca5972fc3bf
1 Tiny C Compiler - C Scripting Everywhere - The Smallest ANSI C compiler
2 -----------------------------------------------------------------------
4 Features:
5 --------
7 - SMALL! You can compile and execute C code everywhere, for example on
8   rescue disks (29KB for x86 TCC executable).
10 - FAST! tcc generates optimized x86 code. No byte code
11   overhead. Compiles, assemble and link about 7 times faster than 'gcc
12   -O0'.
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.
18 - Compile and execute C source directly. No linking or assembly
19   necessary. Full C preprocessor included. 
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.
25 Documentation:
26 -------------
28 1) Installation
30 ***TCC currently only work on Linux x86***.
32 Type 'make install' to compile and install tcc in /usr/local/bin and
33 /usr/local/lib/tcc.
35 2) Introduction
37 We assume here that you know ANSI C. Look at the example ex1.c to know
38 what the programs look like.
40 The main limitation of tcc is that you cannot use floats. 
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.
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.
52 3) Invokation
54 '-Idir' : specify an additionnal include path. The
55 default ones are: /usr/include, /usr/lib/tcc, /usr/local/lib/tcc.
57 '-Dsym' : define preprocessor symbol 'sym' to 1.
59 '-lxxx' : dynamically link your program with library
60 libxxx.so. Standard library paths are checked, including those
61 specificed with LD_LIBRARY_PATH.
63 Only one source code can be compiled. If you have multiple source
64 files, add one which includes all your sources.
66 4) Examples
68 ex1.c: simplest example (hello world). Can also be launched directly
69 as a script: './ex1.c'.
71 ex2.c: more complicated example: find a number with the four
72 operations given a list of numbers (benchmark).
74 ex3.c: compute fibonacci numbers (benchmark).
76 ex4.c: more complicated: X11 program. Very complicated test in fact
77 because standard headers are being used !
79 ex5.c: 'hello world' with standard glibc headers.
81 tcc.c: TCC can of course compile itself. Used to check the code
82 generator.
84 prog.c: auto test for TCC which tests many subtle possible bugs. Used
85 when doing 'make test'.
87 Exact differences with ANSI C:
88 -----------------------------
90 - Preprocessor: the preprocessor tokens are the same as C. It means
91   that in some rare cases, preprocessed numbers are not handled
92   exactly as in ANSI C. This approach has the advantage of being
93   simpler and FAST!
95 - Types: floating point numbers are not supported yet.
97 - Bit fields are not supported.
99 - Linking: extern variables must appear in a referenced dll and cannot
100   appear in current source.
102 Supported ANSI C extensions:
103 ---------------------------
105 - 'inline' keyword is ignored (ISOC99).
107 - 'restrict' keyword is ignored (ISOC99).
109 - '__func__' is a string variable containing the current function name (ISOC99).
111 - Variadic macros: __VA_ARGS__ can be used for function-like macros (ISOC99):
112    #define dprintf(level, __VA_ARGS__) printf(__VA_ARGS__).
114 - Declarations can appear anywhere in a block (ISOC99).
116 - Array and struct/union elements can be initialized in any order by
117   using designators (.e.g. { [0].x = 1 }) (ISOC99).
119 - Compound initializers are supported (e.g. int *p = (int []){ 1, 2,
120   3}) (ISOC99).
122 - '#!' at the start of a line is ignored to allow scripting.
124 - Binary digits can be entered ('0b101' instead of '5').
126 Technical Description:
127 ---------------------
129 This is not my first C compiler (see my 'fbcc' compiler) but it
130 contains the first C preprocessor I wrote. The project started as a
131 joke to make the smallest C compiler. Then I expanded it torward
132 ISOC99 compliance. This C compiler is particular because each feature
133 was added while trying to be as simple and compact as possible. For
134 example, no intermediate structure is used to store code or
135 expressions.
137 The TCC code generator directly generates linked binary code. It is
138 rather unusual these days (see gcc for example which generates text
139 assembly), but it allows to be very fast and surprisingly not so
140 complicated.
142 The TCC code generator is register based. It means that it could even
143 generate good code for RISC processors. On x86, three temporary
144 registers are used. When more registers are needed, one register is
145 flushed in a new local variable.
147 Constant propagation is done for all operations. Multiplications and
148 divisions are optimized to shifts when appropriate. Comparison
149 operators are optimized by maintaining a special cache for the
150 processor flags. &&, || and ! are optimized by maintaining a special
151 'jmp target' value. No other jmp optimization is currently performed
152 because it would require to store the code in a more abstract fashion.
154 The types and values descriptions are stored in a single 'int'
155 variable (see VT_xxx constants). It was choosen in the first stages of
156 development when tcc was much simpler. Now, it may not be the best
157 solution.
159 License:
160 -------
162 TCC is distributed under the GNU General Public License (see COPYING
163 file). 
165 I accept only patches where you give your copyright explictely to me
166 to simplify licensing issues.
168 Fabrice Bellard - Nov 17, 2001.