Alien-TinyCC

 view release on metacpan or  search on metacpan

src/tcc-doc.texi  view on Meta::CPAN

@end table

Warning options:

@table @option
@item -w
Disable all warnings.

@end table

Note: each of the following warning options has a negative form beginning with
@option{-Wno-}.

@table @option
@item -Wimplicit-function-declaration
Warn about implicit function declaration.

@item -Wunsupported
Warn about unsupported GCC features that are ignored by TCC.

@item -Wwrite-strings
Make string constants be of type @code{const char *} instead of @code{char
*}.

@item -Werror
Abort compilation if warnings are issued.

@item -Wall 
Activate all warnings, except @option{-Werror}, @option{-Wunusupported} and
@option{-Wwrite-strings}.

@end table

Linker options:

@table @option
@item -Ldir
Specify an additional static library path for the @option{-l} option. The
default library paths are @file{/usr/local/lib}, @file{/usr/lib} and @file{/lib}.

@item -lxxx
Link your program with dynamic library libxxx.so or static library
libxxx.a. The library is searched in the paths specified by the
@option{-L} option and @env{LIBRARY_PATH} variable.

@item -Bdir
Set the path where the tcc internal libraries (and include files) can be
found (default is @file{PREFIX/lib/tcc}).

@item -shared
Generate a shared library instead of an executable.

@item -soname name
set name for shared library to be used at runtime

@item -static
Generate a statically linked executable (default is a shared linked
executable).

@item -rdynamic
Export global symbols to the dynamic linker. It is useful when a library
opened with @code{dlopen()} needs to access executable symbols.

@item -r
Generate an object file combining all input files.

@item -Wl,-rpath=path
Put custom seatch path for dynamic libraries into executable.

@item -Wl,--oformat=fmt
Use @var{fmt} as output format. The supported output formats are:
@table @code
@item elf32-i386
ELF output format (default)
@item binary
Binary image (only for executable output)
@item coff
COFF output format (only for executable output for TMS320C67xx target)
@end table

@item -Wl,-subsystem=console/gui/wince/...
Set type for PE (Windows) executables.

@item -Wl,-[Ttext=# | section-alignment=# | file-alignment=# | image-base=# | stack=#]
Modify executable layout.

@item -Wl,-Bsymbolic
Set DT_SYMBOLIC tag.

@end table

Debugger options:

@table @option
@item -g
Generate run time debug information so that you get clear run time
error messages: @code{ test.c:68: in function 'test5()': dereferencing
invalid pointer} instead of the laconic @code{Segmentation
fault}.

@item -b
Generate additional support code to check
memory allocations and array/pointer bounds. @option{-g} is implied. Note
that the generated code is slower and bigger in this case.

Note: @option{-b} is only available on i386 for the moment.

@item -bt N
Display N callers in stack traces. This is useful with @option{-g} or
@option{-b}.

@end table

Misc options:

@table @option
@item -MD
Generate makefile fragment with dependencies.

@item -MF depfile
Use @file{depfile} as output for -MD.

src/tcc-doc.texi  view on Meta::CPAN

@item Identifiers are the same as C, so you cannot use '.' or '$'.

@item Only 32 bit integer numbers are supported.

@end itemize

@section Expressions

@itemize

@item Integers in decimal, octal and hexa are supported.

@item Unary operators: +, -, ~.

@item Binary operators in decreasing priority order:

@enumerate
@item *, /, %
@item &, |, ^
@item +, -
@end enumerate

@item A value is either an absolute number or a label plus an offset. 
All operators accept absolute values except '+' and '-'. '+' or '-' can be
used to add an offset to a label. '-' supports two labels only if they
are the same or if they are both defined and in the same section.

@end itemize

@section Labels

@itemize

@item All labels are considered as local, except undefined ones.

@item Numeric labels can be used as local @code{gas}-like labels. 
They can be defined several times in the same source. Use 'b'
(backward) or 'f' (forward) as suffix to reference them:

@example
 1:
      jmp 1b /* jump to '1' label before */
      jmp 1f /* jump to '1' label after */
 1:
@end example

@end itemize

@section Directives
@cindex assembler directives
@cindex directives, assembler
@cindex align directive
@cindex skip directive
@cindex space directive
@cindex byte directive
@cindex word directive
@cindex short directive
@cindex int directive
@cindex long directive
@cindex quad directive
@cindex globl directive
@cindex global directive
@cindex section directive
@cindex text directive
@cindex data directive
@cindex bss directive
@cindex fill directive
@cindex org directive
@cindex previous directive
@cindex string directive
@cindex asciz directive
@cindex ascii directive

All directives are preceded by a '.'. The following directives are
supported:

@itemize
@item .align n[,value]
@item .skip n[,value]
@item .space n[,value]
@item .byte value1[,...]
@item .word value1[,...]
@item .short value1[,...]
@item .int value1[,...]
@item .long value1[,...]
@item .quad immediate_value1[,...]
@item .globl symbol
@item .global symbol
@item .section section
@item .text
@item .data
@item .bss
@item .fill repeat[,size[,value]]
@item .org n
@item .previous
@item .string string[,...]
@item .asciz string[,...]
@item .ascii string[,...]
@end itemize

@section X86 Assembler
@cindex assembler

All X86 opcodes are supported. Only ATT syntax is supported (source
then destination operand order). If no size suffix is given, TinyCC
tries to guess it from the operand sizes.

Currently, MMX opcodes are supported but not SSE ones.

@node linker
@chapter TinyCC Linker
@cindex linker

@section ELF file generation
@cindex ELF

TCC can directly output relocatable ELF files (object files),
executable ELF files and dynamic ELF libraries without relying on an
external linker.

Dynamic ELF libraries can be output but the C compiler does not generate
position independent code (PIC). It means that the dynamic library
code generated by TCC cannot be factorized among processes yet.

TCC linker eliminates unreferenced object code in libraries. A single pass is
done on the object and library list, so the order in which object files and
libraries are specified is important (same constraint as GNU ld). No grouping
options (@option{--start-group} and @option{--end-group}) are supported.

@section ELF file loader

TCC can load ELF object files, archives (.a files) and dynamic
libraries (.so).

@section PE-i386 file generation
@cindex PE-i386

TCC for Windows supports the native Win32 executable file format (PE-i386).  It
generates EXE files (console and gui) and DLL files.

For usage on Windows, see also tcc-win32.txt.

@section GNU Linker Scripts
@cindex scripts, linker
@cindex linker scripts
@cindex GROUP, linker command
@cindex FILE, linker command
@cindex OUTPUT_FORMAT, linker command
@cindex TARGET, linker command

Because on many Linux systems some dynamic libraries (such as
@file{/usr/lib/libc.so}) are in fact GNU ld link scripts (horrible!),
the TCC linker also supports a subset of GNU ld scripts.

The @code{GROUP} and @code{FILE} commands are supported. @code{OUTPUT_FORMAT}
and @code{TARGET} are ignored.

Example from @file{/usr/lib/libc.so}:
@example
/* GNU ld script
   Use the shared library, but some functions are only in
   the static library, so try that secondarily.  */
GROUP ( /lib/libc.so.6 /usr/lib/libc_nonshared.a )
@end example

@node Bounds
@chapter TinyCC Memory and Bound checks
@cindex bound checks
@cindex memory checks

This feature is activated with the @option{-b} (@pxref{Invoke}).

Note that pointer size is @emph{unchanged} and that code generated
with bound checks is @emph{fully compatible} with unchecked
code. When a pointer comes from unchecked code, it is assumed to be
valid. Even very obscure C code with casts should work correctly.

For more information about the ideas behind this method, see
@url{http://www.doc.ic.ac.uk/~phjk/BoundsChecking.html}.

Here are some examples of caught errors:

@table @asis

@item Invalid range with standard string function:
@example
@{
    char tab[10];
    memset(tab, 0, 11);
@}
@end example

@item Out of bounds-error in global or local arrays:
@example
@{
    int tab[10];
    for(i=0;i<11;i++) @{
        sum += tab[i];
    @}
@}
@end example

@item Out of bounds-error in malloc'ed data:
@example
@{
    int *tab;
    tab = malloc(20 * sizeof(int));
    for(i=0;i<21;i++) @{
        sum += tab4[i];
    @}
    free(tab);
@}
@end example

@item Access of freed memory:
@example
@{
    int *tab;
    tab = malloc(20 * sizeof(int));
    free(tab);
    for(i=0;i<20;i++) @{
        sum += tab4[i];
    @}
@}
@end example

@item Double free:
@example
@{
    int *tab;
    tab = malloc(20 * sizeof(int));
    free(tab);
    free(tab);
@}
@end example

@end table

@node Libtcc
@chapter The @code{libtcc} library

The @code{libtcc} library enables you to use TCC as a backend for
dynamic code generation. 

Read the @file{libtcc.h} to have an overview of the API. Read
@file{libtcc_test.c} to have a very simple example.

The idea consists in giving a C string containing the program you want
to compile directly to @code{libtcc}. Then you can access to any global
symbol (function or variable) defined.

@node devel
@chapter Developer's guide

This chapter gives some hints to understand how TCC works. You can skip
it if you do not intend to modify the TCC code.

@section File reading

The @code{BufferedFile} structure contains the context needed to read a
file, including the current line number. @code{tcc_open()} opens a new
file and @code{tcc_close()} closes it. @code{inp()} returns the next
character.

@section Lexer

@code{next()} reads the next token in the current
file. @code{next_nomacro()} reads the next token without macro
expansion.

@code{tok} contains the current token (see @code{TOK_xxx})
constants. Identifiers and keywords are also keywords. @code{tokc}
contains additional infos about the token (for example a constant value
if number or string token).

@section Parser

The parser is hardcoded (yacc is not necessary). It does only one pass,
except:

@itemize

@item For initialized arrays with unknown size, a first pass 
is done to count the number of elements.

@item For architectures where arguments are evaluated in 
reverse order, a first pass is done to reverse the argument order.

@end itemize

@section Types

The types are stored in a single 'int' variable. It was chosen in the
first stages of development when tcc was much simpler. Now, it may not
be the best solution.

@example
#define VT_INT        0  /* integer type */
#define VT_BYTE       1  /* signed byte type */
#define VT_SHORT      2  /* short type */
#define VT_VOID       3  /* void type */
#define VT_PTR        4  /* pointer */
#define VT_ENUM       5  /* enum definition */
#define VT_FUNC       6  /* function type */
#define VT_STRUCT     7  /* struct/union definition */
#define VT_FLOAT      8  /* IEEE float */
#define VT_DOUBLE     9  /* IEEE double */
#define VT_LDOUBLE   10  /* IEEE long double */
#define VT_BOOL      11  /* ISOC99 boolean type */

src/tcc-doc.texi  view on Meta::CPAN

#define VT_BITFIELD   0x0040  /* bitfield modifier */
#define VT_CONSTANT   0x0800  /* const modifier */
#define VT_VOLATILE   0x1000  /* volatile modifier */
#define VT_SIGNED     0x2000  /* signed type */

#define VT_STRUCT_SHIFT 18   /* structure/enum name shift (14 bits left) */
@end example

When a reference to another type is needed (for pointers, functions and
structures), the @code{32 - VT_STRUCT_SHIFT} high order bits are used to
store an identifier reference.

The @code{VT_UNSIGNED} flag can be set for chars, shorts, ints and long
longs.

Arrays are considered as pointers @code{VT_PTR} with the flag
@code{VT_ARRAY} set. Variable length arrays are considered as special
arrays and have flag @code{VT_VLA} set instead of @code{VT_ARRAY}.

The @code{VT_BITFIELD} flag can be set for chars, shorts, ints and long
longs. If it is set, then the bitfield position is stored from bits
VT_STRUCT_SHIFT to VT_STRUCT_SHIFT + 5 and the bit field size is stored
from bits VT_STRUCT_SHIFT + 6 to VT_STRUCT_SHIFT + 11.

@code{VT_LONG} is never used except during parsing.

During parsing, the storage of an object is also stored in the type
integer:

@example
#define VT_EXTERN  0x00000080  /* extern definition */
#define VT_STATIC  0x00000100  /* static variable */
#define VT_TYPEDEF 0x00000200  /* typedef definition */
#define VT_INLINE  0x00000400  /* inline definition */
#define VT_IMPORT  0x00004000  /* win32: extern data imported from dll */
#define VT_EXPORT  0x00008000  /* win32: data exported from dll */
#define VT_WEAK    0x00010000  /* win32: data exported from dll */
@end example

@section Symbols

All symbols are stored in hashed symbol stacks. Each symbol stack
contains @code{Sym} structures.

@code{Sym.v} contains the symbol name (remember
an idenfier is also a token, so a string is never necessary to store
it). @code{Sym.t} gives the type of the symbol. @code{Sym.r} is usually
the register in which the corresponding variable is stored. @code{Sym.c} is
usually a constant associated to the symbol like its address for normal
symbols, and the number of entries for symbols representing arrays.
Variable length array types use @code{Sym.c} as a location on the stack
which holds the runtime sizeof for the type.

Four main symbol stacks are defined:

@table @code

@item define_stack
for the macros (@code{#define}s).

@item global_stack
for the global variables, functions and types.

@item local_stack
for the local variables, functions and types.

@item global_label_stack
for the local labels (for @code{goto}).

@item label_stack
for GCC block local labels (see the @code{__label__} keyword).

@end table

@code{sym_push()} is used to add a new symbol in the local symbol
stack. If no local symbol stack is active, it is added in the global
symbol stack.

@code{sym_pop(st,b)} pops symbols from the symbol stack @var{st} until
the symbol @var{b} is on the top of stack. If @var{b} is NULL, the stack
is emptied.

@code{sym_find(v)} return the symbol associated to the identifier
@var{v}. The local stack is searched first from top to bottom, then the
global stack.

@section Sections

The generated code and datas are written in sections. The structure
@code{Section} contains all the necessary information for a given
section. @code{new_section()} creates a new section. ELF file semantics
is assumed for each section.

The following sections are predefined:

@table @code

@item text_section
is the section containing the generated code. @var{ind} contains the
current position in the code section.

@item data_section
contains initialized data

@item bss_section
contains uninitialized data

@item bounds_section
@itemx lbounds_section
are used when bound checking is activated

@item stab_section
@itemx stabstr_section
are used when debugging is actived to store debug information

@item symtab_section
@itemx strtab_section
contain the exported symbols (currently only used for debugging).

@end table

@section Code generation
@cindex code generation

@subsection Introduction

The TCC code generator directly generates linked binary code in one
pass. It is rather unusual these days (see gcc for example which
generates text assembly), but it can be very fast and surprisingly
little complicated.

The TCC code generator is register based. Optimization is only done at
the expression level. No intermediate representation of expression is
kept except the current values stored in the @emph{value stack}.

On x86, three temporary registers are used. When more registers are
needed, one register is spilled into a new temporary variable on the stack.

@subsection The value stack
@cindex value stack, introduction

When an expression is parsed, its value is pushed on the value stack
(@var{vstack}). The top of the value stack is @var{vtop}. Each value
stack entry is the structure @code{SValue}.