diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Changelog | 520 | ||||
| -rw-r--r-- | docs/CodingStyle.md | 10 | ||||
| -rw-r--r-- | docs/TODO | 92 | ||||
| -rw-r--r-- | docs/config.texi.in | 1 | ||||
| -rw-r--r-- | docs/tcc-doc.texi | 1300 | ||||
| -rw-r--r-- | docs/texi2pod.pl | 427 |
6 files changed, 2350 insertions, 0 deletions
diff --git a/docs/Changelog b/docs/Changelog new file mode 100644 index 0000000..7cc19c8 --- /dev/null +++ b/docs/Changelog @@ -0,0 +1,520 @@ +Version 0.9.27: + +Licensing: + +- TinyCC partly relicensed to MIT license + +User interface: + +- define __STDC_HOSTED__ (Michael Matz, Urs Janssen) +- added support for CPATH, C_INCLUDE_PATH and LD_LIBRARY_PATH (Andrew Aladjev +and Urs Janssen) +- added option -norunsrc to control argv[0] with tcc -run (James Lyon) +- improve --with-libgcc configure help (grischka) +- improve error message when memory is full (grischka) +- improve wording about compiler switches in documentation (Thomas Preud'homme) +- use GNU triplet prefix for cross compiler names (Thomas Preud'homme) +- ignore unknown linker optimization and as-needed option (Austin English) + +Features: + +- added ABI tests with native compiler using libtcc (James Lyon) +- added CMake build system with support for cross-compilation (James Lyon) +- improved variable length array support (James Lyon) +- add the possibility to use noname functions by ordinal (YX Hao) +- add a install-strip target to install tcc (Thomas Preud'homme) +- add runtime selection of float ABI on ARM (Thomas Preud'homme) +- add shared lib support on x86-64 (Michael Matz) + +Platforms: +- support Debian GNU/kfreeBSD 64bit userspace (Thomas Preud'homme) +- fix GNU/Hurd interpreter path (Thomas Preud'homme) +- fix configure script for FreeBSD host (Thomas Preud'homme) +- make tcc -run work reliably on ARM by flushing caches (Thomas Preud'homme) +- many x86-64 ABI fixes incl. XMM register passing (James Lyon) +- improve compatibility with mingw's long double (James Lyon) +- avoid .stabstr section name to be truncated on win32 (Roy) +- add support for load/store of _Bool value (Thomas Preud'homme) +- detect instruction with incorrect operands on x86-64 (Thomas Preud'homme) +- improved relocations on ARM (Thomas Preud'homme) +- add va_* macro implementation for ARM (Thomas Preud'homme) +- define __ARM_EABI__, __ARMEL__ and __ARM_PCS_VFP (Thomas Preud'homme) +- provide a runtime library for ARM (Thomas Preud'homme) +- vastly improved support for ARM hard float calling convention +(Thomas Preud'homme, Daniel Glöckner) +- tcc can uses libtcc1 on ARM (Thomas Preud'homme) +- use __fixdfdi for all float to integer conversion (grischka) +- simplify startup code for unix platforms (grischka) +- improve ELF generated on ARM (Thomas Preud'homme) +- add support for thumb to ARM relocation (Thomas Preud'homme) +- fix globbing to match MSVC on Windows (Thomas Preud'homme) +- deprecate FPA and OABI support for ARM (Thomas Preud'homme) +- warn about softfloat not being supported on ARM (Thomas Preud'homme) + +Bug fixes: +- many code clean up (Urs Janssen, grischka) +- fixes of other's patches (grischka, Ramsay Jones, Michael Matz) +- fix documentation about __TINYC__ (Urs Janssen) +- improve build of documentation (Urs Janssen) +- improve build instructions (Jov) +- switch from texi2html to makeinfo --html to build tcc-doc.html (James Lyon) +- improve out of tree build (James Lyon) +- improved passing and returning of struct (James Lyon) +- fix CMake build on i386 and x86-64 (James Lyon) +- fix i386 calling convention issue (James Lyon) +- fix error in Windows build of tests (James Lyon) +- fix x86-64 long double passing (James Lyon) +- fix crash with undefined struct (grischka) +- normalize slashes on win32 to always use backslashes (grischka) +- use runtime function for float to int conversion on i386 (grischka) +- improved documentation for include and lib lookup on win32 (grischka) +- detect redefinition of function (Thomas Preud'homme) +- detect the use of array of functions (Thomas Preud'homme) +- detect use of enumerator with wrong enumeration (Thomas Preud'homme) +- detect redefinition of enumerator or enumeration (Thomas Preud'homme) +- set the user-defined library search paths first (Vittorio Giovara) +- detect usage of incomplete types inside struct/union (Amine Najahi) +- various macro bug fixes (Joseph Poirier) +- avoid wrong trigger of assert on x86-64 platform (Thomas Preud'homme) +- fix NaN comparison (Thomas Preud'homme) +- use libtcc for static linking with runtime library (Thomas Preud'homme) +- fix negation of 0.0 and -0.0 values (Thomas Preud'homme) +- fix use of long long as if condition (Thomas Preud'homme) +- disable bound check if libgcc is used (Thomas Preud'homme) +- error out when casting to void (grischka) +- remove circular dependency in Makefile (grischka) +- stop preventing gcc to do strict aliasing (grischka) +- fix Windows build of tcc (grischka) +- build runtime library for arm cross compiler (Thomas Preud'homme) +- fix installation of arm cross-compiler (Thomas Preud'homme) +- add basic test for cross-compiler (Thomas Preud'homme) +- fix failure when generating PE on x86-64 (Archidemon) +- fix floating point unary minus and plus (Michael Matz) +- add more tests for signed zero float (Michael Matz) +- fix precision of double on x86-64 (Vincent Lefevre) +- fix bound checking of argv with -run switch (Kirill Smelkov) +- work around a wine cmd bug when building tcc on Windows (Austin English) +- reenable some bound check tests (grischka) +- boundtest.c lookup honors VPATH (grischka) +- diff compared to CC in test[123]b? are now errors (grischka) +- fix test3 on Windows (grischka) +- prevent gcc from building (non functional) libtcc.a (grischka) +- fix warning related to PE file generation on x86-64 (grischka) +- stop mixing ordinary and implicit rule in Makefile (Iavael) +- fix integer to double conversion on ARM (Thomas Preud'homme) +- fix parameter passing of structure < 4 bytes on ARM (Thomas Preud'homme) +- disable builtin_frame_address test on ARM due to gcc bug (Thomas Preud'homme) +- fix initialization of struct on ARM (Thomas Preud'homme) +- fix parameter passing of (unsigned) long long bitfield (Thomas Preud'homme) +- improve float to integer tests (Thomas Preud'homme) +- fix relocation of Thumb branch to ARM function (Thomas Preud'homme) +- fix char wrong compatibility with [un]signed char (Thomas Preud'homme) +- choose the code to compile based on target in libtcc1 (Thomas Preud'homme) +- fix various clang warnings (Thomas Preud'homme) +- don't hardcode tcc in Makefile for tests (Thomas Preud'homme) +- fix relocation of __bound_init bound checking code (Thomas Preud'homme) +- accept only one basic type for a given variable (Thomas Preud'homme) +- fix error when using va_* with tcc using libgcc (Thomas Preud'homme) +- support GOT32 and PLT32 reloc on the same symbol (Thomas Preud'homme) +- fix memory leak due to symbol attributes (mingodad) +- partially fix bound checking of argv and arge (Thomas Preud'homme) +- fix possible dereference when getting name of symbol (grischka) +- fix va_list type definition on x86-64 (Daniel Glöckner) +- reduce number of scan-build false positive (mingodad) + +version 0.9.26: + +User interface: +- -MD/-MF (automatically generate dependencies for make) +- -pthread option (same as -D_REENTRANT -lpthread) (Henry Kroll III) +- -m32/-m64 to re-exec cross compiler (Henry Kroll III) +- -Wl, Mimic all GNU -option forms supported by ld (Kirill Smelkov) +- new LIBTCCAPI tcc_set_options() (grischka) + +Platforms: +- Many improvements for x86-64 target (Shinichiro Hamaji, Michael Matz, grischka) +- x86-64 assembler (Frederic Feret) +- Many improvements for ARM target (Daniel Glöckner, Thomas Preud'homme) +- Support WinCE PE ARM (Timo VJ Lahde) +- Support ARM hardfloat calling convention (Thomas Preud'homme) +- Support SELinux (Security-Enhanced Linux) (Henry Kroll III) +- Support Debian GNU/kFreeBSD kernels (Pierre Chifflier) +- Support GNU/Hurd kernels (Thomas Preud'homme) +- Support OSX (tcc -run only) (Milutin Jovanovic) +- Support multiarch configuration (Thomas Preud'homme) +- Support out-of-tree build (Akim Demaille) + +Features: +- C99 variable length arrays (Thomas Preud'homme & Joe Soroka) +- Asm labels for variables and functions (Thomas Preud'homme) +- STT_GNU_IFUNC (Indirect functions as externals) (Thomas Preud'homme) +- More tests (tests2) (Milutin Jovanovic) + +version 0.9.25: + +- first support for x86-64 target (Shinichiro Hamaji) +- support µClibc +- split tcc.c into tcc.h libtcc.c tccpp.c tccgen.c tcc.c +- improved preprocess output with linenumbers and spaces preserved +- tcc_relocate now copies code into user buffer +- fix bitfields with non-int types and in unions +- improve ARM cross-compiling (Daniel Glöckner) +- link stabstr sections from multiple objects +- better (still limited) support for multiple TCCStates + +version 0.9.24: + +- added verbosity levels -v, -vv, -vvv +- Accept standard input as an inputstream (Hanzac Chen) +- Support c89 compilers other than gcc (Hanzac Chen) +- -soname linker option (Marc Andre Tanner) +- Just warn about unknown directives, ignore quotes in #error/#warning +- Define __STDC_VERSION__=199901L (477) +- Switch to newer tccpe.c (includes support for resources) +- Handle backslashes within #include/#error/#warning +- Import changesets (part 4) 428,457,460,467: defines for openbsd etc. +- Use _WIN32 for a windows hosted tcc and define it for the PE target, + otherwise define __unix / __linux (Detlef Riekenberg) +- Import changesets (part 3) 409,410: ARM EABI by Daniel Glöckner +- Some in-between fixes: + TCC -E no longer hangs with macro calls involving newlines. + (next_nomacro1 now advances the read-pointer with TOK_LINEFEED) + Global cast (int g_i = 1LL;) no longer crashes tcc. + (nocode_wanted is initially 1, and only 0 for gen_function) + On win32 now tcc.exe finds 'include' & 'lib' even if itself is in 'bin'. + (new function w32_tcc_lib_path removes 'bin' if detected) + Added quick build batch file for mingw (win32/build-tcc.bat) + Last added case label optimization (455) produced wrong code. Reverted. + +- Import more changesets from Rob Landley's fork (part 2): + 487: Handle long long constants in gen_opic() (Rob Landley) + 484: Handle parentheses within __attribute__((...)) (Rob Landley) + 480: Remove a goto in decl_initializer_alloc (Rob Landley) + 475: Fix dereferences in inline assembly output (Joshua Phillips) + 474: Cast ptrs to ints of different sizes correctly (Joshua Phillips) + 473: Fix size of structs with empty array member (Joshua Phillips) + 470: No warning for && and || with mixed pointers/integers (Rob Landley) + 469: Fix symbol visibility problems in the linker (Vincent Pit) + 468: Allow && and || involving pointer arguments (Rob Landley) + 455: Optimize case labels with no code in between (Zdenek Pavlas) + 450: Implement alloca for x86 (grischka) + 415: Parse unicode escape sequences (Axel Liljencrantz) + 407: Add a simple va_copy() in stdarg.h (Hasso Tepper) + 400: Allow typedef names as symbols (Dave Dodge) + +- Import some changesets from Rob Landley's fork (part 1): + 462: Use LGPL with bcheck.c and il-gen.c + 458: Fix global compound literals (in unary: case '&':) (Andrew Johnson) + 456: Use return code from tcc_output_file in main() (Michael Somos) + 442: Fix indirections with function pointers (***fn)() (grischka) + 441: Fix LL left shift in libtcc1.c:__shldi3 (grischka) + 440: Pass structures and function ptrs through ?: (grischka) + 439: Keep rvalue in bit assignment (bit2 = bit1 = x) (grischka) + 438: Degrade nonportable pointer assignment to warning (grischka) + 437: Call 'saveregs()' before jumping with logical and/or/not (grischka) + 435: Put local static variables into global memory (grischka) + 432/434: Cast double and ptr to bool (grischka) + 420: Zero pad x87 tenbyte long doubles (Felix Nawothnig) + 417: Make 'sizeof' unsigned (Rob Landley) + 397: Fix save_reg for longlongs (Daniel Glöckner) + 396: Fix "invalid relocation entry" problem on ubuntu - (Bernhard Fischer) + +- ignore AS_NEEDED ld command +- mark executable sections as executable when running in memory +- added support for win32 wchar_t (Filip Navara) +- segment override prefix support (Filip Navara) +- normalized slashes in paths (Filip Navara) +- windows style fastcall (Filip Navara) +- support for empty input register section in asm (Filip Navara) +- anonymous union/struct support (Filip Navara) +- fixed parsing of function parameters +- workaround for function pointers in conditional expressions (Dave Dodge) +- initial '-E' option support to use the C preprocessor alone +- discard type qualifiers when comparing function parameters (Dave Dodge) +- Bug fix: A long long value used as a test expression ignores the + upper 32 bits at runtime (Dave Dodge) +- fixed multiple concatenation of PPNUM tokens (initial patch by Dave Dodge) +- fixed multiple typedef specifiers handling +- fixed sign extension in some type conversions (Dave Dodge) + +version 0.9.23: + +- initial PE executable format for windows version (grischka) +- '#pragma pack' support (grischka) +- '#include_next' support (Bernhard Fischer) +- ignore '-pipe' option +- added -f[no-]leading-underscore +- preprocessor function macro parsing fix (grischka) + +version 0.9.22: + +- simple memory optimisations: kernel compilation is 30% faster +- linker symbol definitions fixes +- gcc 3.4 fixes +- fixed value stack full error +- 'packed' attribute support for variables and structure fields +- ignore 'const' and 'volatile' in function prototypes +- allow '_Bool' in bit fields + +version 0.9.21: + +- ARM target support (Daniel Glöckner) +- added '-funsigned-char, '-fsigned-char' and + '-Wimplicit-function-declaration' +- fixed assignment of const struct in struct +- line comment fix (reported by Bertram Felgenhauer) +- initial TMS320C67xx target support (TK) +- win32 configure +- regparm() attribute +- many built-in assembler fixes +- added '.org', '.fill' and '.previous' assembler directives +- '-fno-common' option +- '-Ttext' linker option +- section alignment fixes +- bit fields fixes +- do not generate code for unused inline functions +- '-oformat' linker option. +- added 'binary' output format. + +version 0.9.20: + +- added '-w' option +- added '.gnu.linkonce' ELF sections support +- fixed libc linking when running in memory (avoid 'stat' function + errors). +- extended '-run' option to be able to give several arguments to a C + script. + +version 0.9.19: + +- "alacarte" linking (Dave Long) +- simpler function call +- more strict type checks +- added 'const' and 'volatile' support and associated warnings +- added -Werror, -Wunsupported, -Wwrite-strings, -Wall. +- added __builtin_types_compatible_p() and __builtin_constant_p() +- chars support in assembler (Dave Long) +- .string, .globl, .section, .text, .data and .bss asm directive + support (Dave Long) +- man page generated from tcc-doc.texi +- fixed macro argument substitution +- fixed zero argument macro parsing +- changed license to LGPL +- added -rdynamic option support + +version 0.9.18: + +- header fix (time.h) +- fixed inline asm without operand case +- fixed 'default:' or 'case x:' with '}' after (incorrect C construct accepted + by gcc) +- added 'A' inline asm constraint. + +version 0.9.17: + +- PLT generation fix +- tcc doc fixes (Peter Lund) +- struct parse fix (signaled by Pedro A. Aranda Gutierrez) +- better _Bool lvalue support (signaled by Alex Measday) +- function parameters must be converted to pointers (signaled by Neil Brown) +- sanitized string and character constant parsing +- fixed comment parse (signaled by Damian M Gryski) +- fixed macro function bug (signaled by Philippe Ribet) +- added configure (initial patch by Mitchell N Charity) +- added '-run' and '-v' options (initial patch by vlindos) +- added real date report in __DATE__ and __TIME__ macros + +version 0.9.16: + +- added assembler language support +- added GCC inline asm() support +- fixed multiple variable definitions : uninitialized variables are + created as COMMON symbols. +- optimized macro processing +- added GCC statement expressions support +- added GCC local labels support +- fixed array declaration in old style function parameters +- support casts in static structure initializations +- added various __xxx[__] keywords for GCC compatibility +- ignore __extension__ GCC in an expression or in a type (still not perfect) +- added '? :' GCC extension support + +version 0.9.15: + +- compilation fixes for glibc 2.2, gcc 2.95.3 and gcc 3.2. +- FreeBSD compile fixes. Makefile patches still missing (Carl Drougge). +- fixed file type guessing if '.' is in the path. +- fixed tcc_compile_string() +- add a dummy page in ELF files to fix RX/RW accesses (pageexec at + freemail dot hu). + +version 0.9.14: + +- added #warning. error message if invalid preprocessing directive. +- added CType structure to ease typing (faster parse). +- suppressed secondary hash tables (faster parse). +- rewrote parser by optimizing common cases (faster parse). +- fixed signed long long comparisons. +- fixed 'int a(), b();' declaration case. +- fixed structure init without '{}'. +- correct alignment support in structures. +- empty structures support. +- gcc testsuite now supported. +- output only warning if implicit integer/pointer conversions. +- added static bitfield init. + +version 0.9.13: + +- correct preprocessing token pasting (## operator) in all cases (added + preprocessing number token). +- fixed long long register spill. +- fixed signed long long '>>'. +- removed memory leaks. +- better error handling : processing can continue on link errors. A + custom callback can be added to display error messages. Most + errors do not call exit() now. +- ignore -O, -W, -m and -f options +- added old style function declarations +- added GCC __alignof__ support. +- added GCC typeof support. +- added GCC computed gotos support. +- added stack backtrace in runtime error message. Improved runtime + error position display. + +version 0.9.12: + +- more fixes for || and && handling. +- improved '? :' type handling. +- fixed bound checking generation with structures +- force '#endif' to be in same file as matching '#if' +- #include file optimization with '#ifndef #endif' construct detection +- macro handling optimization +- added tcc_relocate() and tcc_get_symbol() in libtcc. + +version 0.9.11: + +- stdarg.h fix for double type (thanks to Philippe Ribet). +- correct white space characters and added MSDOS newline support. +- fixed invalid implicit function call type declaration. +- special macros such as __LINE__ are defined if tested with defined(). +- fixed '!' operator with relocated address. +- added symbol + offset relocation (fixes some static variable initializers) +- '-l' option can be specified anywhere. '-c' option yields default + output name. added '-r' option for relocatable output. +- fixed '\nnn' octal parsing. +- fixed local extern variables declarations. + +version 0.9.10: + +- fixed lvalue type when saved in local stack. +- fixed '#include' syntax when using macros. +- fixed '#line' bug. +- removed size limit on strings. Unified string constants handling + with variable declarations. +- added correct support for '\xX' in wchar_t strings. +- added support for bound checking in generated executables +- fixed -I include order. +- fixed incorrect function displayed in runtime error. + +version 0.9.9: + +- fixed preprocessor expression parsing for #if/#elif. +- relocated debug info (.stab section). +- relocated bounds info (.bounds section). +- fixed cast to char of char constants ('\377' is -1 instead of 255) +- fixed implicit cast for unary plus. +- strings and '__func__' have now 'char[]' type instead of 'char *' + (fixes sizeof() return value). +- added __start_xxx and __stop_xxx symbols in linker. +- better DLL creation support (option -shared begins to work). +- ELF sections and hash tables are resized dynamically. +- executables and DLLs are stripped by default. + +version 0.9.8: + +- First version of full ELF linking support (generate objects, static + executable, dynamic executable, dynamic libraries). Dynamic library + support is not finished (need PIC support in compiler and some + patches in symbol exporting). +- First version of ELF loader for object (.o) and archive (.a) files. +- Support of simple GNU ld scripts (GROUP and FILE commands) +- Separated runtime library and bound check code from TCC (smaller + compiler core). +- fixed register reload in float compare. +- fixed implicit char/short to int casting. +- allow array type for address of ('&') operator. +- fixed unused || or && result. +- added GCC style variadic macro support. +- optimized bound checking code for array access. +- tcc includes are now in $(prefix)/lib/tcc/include. +- more command line options - more consistent handling of multiple + input files. +- added tcc man page (thanks to Cyril Bouthors). +- uClibc Makefile update +- converted documentation to texinfo format. +- added developper's guide in documentation. + +version 0.9.7: + +- added library API for easy dynamic compilation (see libtcc.h - first + draft). +- fixed long long register spill bug. +- fixed '? :' register spill bug. + +version 0.9.6: + +- added floating point constant propagation (fixes negative floating + point constants bug). + +version 0.9.5: + + - uClibc patches (submitted by Alfonso Martone). + - error reporting fix + - added CONFIG_TCC_BCHECK to get smaller code if needed. + +version 0.9.4: + + - windows port (currently cannot use -g, -b and dll functions). + - faster and simpler I/O handling. + - '-D' option works in all cases. + - preprocessor fixes (#elif and empty macro args) + - floating point fixes + - first code for CIL generation (does not work yet) + +version 0.9.3: + + - better and smaller code generator. + - full ISOC99 64 bit 'long long' support. + - full 32 bit 'float', 64 bit 'double' and 96 bit 'long double' support. + - added '-U' option. + - added assembly sections support. + - even faster startup time by mmaping sections instead of mallocing them. + - added GNUC __attribute__ keyword support (currently supports + 'section' and 'aligned' attributes). + - added ELF file output (only usable for debugging now) + - added debug symbol generation (STAB format). + - added integrated runtime error analysis ('-g' option: print clear + run time error messages instead of "Segmentation fault"). + - added first version of tiny memory and bound checker ('-b' option). + +version 0.9.2: + + - even faster parsing. + - various syntax parsing fixes. + - fixed external relocation handling for variables or functions pointers. + - better function pointers type handling. + - can compile multiple files (-i option). + - ANSI C bit fields are supported. + - beginning of float/double/long double support. + - beginning of long long support. + +version 0.9.1: + + - full ISOC99 initializers handling. + - compound literals. + - structures handle in assignments and as function param or return value. + - wide chars and strings. + - macro bug fix + +version 0.9: + - initial version. diff --git a/docs/CodingStyle.md b/docs/CodingStyle.md new file mode 100644 index 0000000..303c1fb --- /dev/null +++ b/docs/CodingStyle.md @@ -0,0 +1,10 @@ +TinyCC Coding Style +========================== +Lines should be no more than 80 columns long. + +Indentation +-------------------------------------- +Turn on a "fill tabs with spaces" option in your editor. + +Be also careful that some files are indented with 2 spaces (when they +have large indentation) while most are indented with 4 spaces. diff --git a/docs/TODO b/docs/TODO new file mode 100644 index 0000000..ea57823 --- /dev/null +++ b/docs/TODO @@ -0,0 +1,92 @@ +TODO list: + +Bugs: + +- fix macro substitution with nested definitions (ShangHongzhang) +- FPU st(0) is left unclean (kwisatz haderach). Incompatible with + optimized gcc/msc code + +- constructors +- cast bug (Peter Wang) +- define incomplete type if defined several times (Peter Wang). +- test binutils/gcc compile +- tci patch + argument. +- see -lxxx bug (Michael Charity). +- see transparent union pb in /urs/include/sys/socket.h +- precise behaviour of typeof with arrays ? (__put_user macro) + but should suffice for most cases) +- handle '? x, y : z' in unsized variable initialization (',' is + considered incorrectly as separator in preparser) +- transform functions to function pointers in function parameters + (net/ipv4/ip_output.c) +- fix function pointer type display +- check lcc test suite -> fix bitfield binary operations +- check section alignment in C +- fix invalid cast in comparison 'if (v == (int8_t)v)' +- finish varargs.h support (gcc 3.2 testsuite issue) +- fix static functions declared inside block +- fix multiple unions init +- sizeof, alignof, typeof can still generate code in some cases. +- Fix the remaining libtcc memory leaks. +- make libtcc fully reentrant (except for the compilation stage itself). + +Bound checking: + +- '-b' bug. +- fix bound exit on RedHat 7.3 +- setjmp is not supported properly in bound checking. +- fix bound check code with '&' on local variables (currently done + only for local arrays). +- bound checking and float/long long/struct copy code. bound + checking and symbol + offset optimization + +Missing features: + +- disable-asm and disable-bcheck options +- __builtin_expect() +- improve '-E' option. +- atexit (Nigel Horne) +- packed attribute +- C99: add complex types (gcc 3.2 testsuite issue) +- postfix compound literals (see 20010124-1.c) + +Optimizations: + +- suppress specific anonymous symbol handling +- more parse optimizations (=even faster compilation) +- memory alloc optimizations (=even faster compilation) +- optimize VT_LOCAL + const +- better local variables handling (needed for other targets) + +Not critical: + +- C99: fix multiple compound literals inits in blocks (ISOC99 + normative example - only relevant when using gotos! -> must add + boolean variable to tell if compound literal was already + initialized). +- add PowerPC or ARM code generator and improve codegen for RISC (need + to suppress VT_LOCAL and use a base register instead). +- interactive mode / integrated debugger +- fix preprocessor symbol redefinition +- better constant opt (&&, ||, ?:) +- add portable byte code generator and interpreter for other + unsupported architectures. +- C++: variable declaration in for, minimal 'class' support. +- win32: __intxx. use resolve for bchecked malloc et al. + check exception code (exception filter func). +- handle void (__attribute__() *ptr)() + +Fixed (probably): + +- bug with defines: + #define spin_lock(lock) do { } while (0) + #define wq_spin_lock spin_lock + #define TEST() wq_spin_lock(a) +- typedefs can be structure fields +- see bugfixes.diff + improvement.diff from Daniel Glockner +- long long constant evaluation +- add alloca() +- gcc '-E' option. +- #include_next support for /usr/include/limits ? +- function pointers/lvalues in ? : (linux kernel net/core/dev.c) +- win32: add __stdcall, check GetModuleHandle for dlls. diff --git a/docs/config.texi.in b/docs/config.texi.in new file mode 100644 index 0000000..259ef19 --- /dev/null +++ b/docs/config.texi.in @@ -0,0 +1 @@ +@set VERSION ${TCC_VERSION} diff --git a/docs/tcc-doc.texi b/docs/tcc-doc.texi new file mode 100644 index 0000000..c673c2c --- /dev/null +++ b/docs/tcc-doc.texi @@ -0,0 +1,1300 @@ +\input texinfo @c -*- texinfo -*- +@c %**start of header +@setfilename tcc-doc.info +@settitle Tiny C Compiler Reference Documentation +@dircategory Software development +@direntry +* TCC: (tcc-doc). The Tiny C Compiler. +@end direntry +@c %**end of header + +@include config.texi + +@iftex +@titlepage +@afourpaper +@sp 7 +@center @titlefont{Tiny C Compiler Reference Documentation} +@sp 3 +@end titlepage +@headings double +@end iftex + +@contents + +@node Top, Introduction, (dir), (dir) +@top Tiny C Compiler Reference Documentation + +This manual documents version @value{VERSION} of the Tiny C Compiler. + +@menu +* Introduction:: Introduction to tcc. +* Invoke:: Invocation of tcc (command line, options). +* Clang:: ANSI C and extensions. +* asm:: Assembler syntax. +* linker:: Output file generation and supported targets. +* Bounds:: Automatic bounds-checking of C code. +* Libtcc:: The libtcc library. +* devel:: Guide for Developers. +@end menu + + +@node Introduction +@chapter Introduction + +TinyCC (aka TCC) is a small but hyper fast C compiler. Unlike other C +compilers, it is meant to be self-relying: you do not need an +external assembler or linker because TCC does that for you. + +TCC compiles so @emph{fast} that even for big projects @code{Makefile}s may +not be necessary. + +TCC not only supports ANSI C, but also most of the new ISO C99 +standard and many GNUC extensions including inline assembly. + +TCC can also be used to make @emph{C scripts}, i.e. pieces of C source +that you run as a Perl or Python script. Compilation is so fast that +your script will be as fast as if it was an executable. + +TCC can also automatically generate memory and bound checks +(@pxref{Bounds}) while allowing all C pointers operations. TCC can do +these checks even if non patched libraries are used. + +With @code{libtcc}, you can use TCC as a backend for dynamic code +generation (@pxref{Libtcc}). + +TCC mainly supports the i386 target on Linux and Windows. There are alpha +ports for the ARM (@code{arm-tcc}) and the TMS320C67xx targets +(@code{c67-tcc}). More information about the ARM port is available at +@url{http://lists.gnu.org/archive/html/tinycc-devel/2003-10/msg00044.html}. + +For usage on Windows, see also @url{tcc-win32.txt}. + +@node Invoke +@chapter Command line invocation + +@section Quick start + +@example +@c man begin SYNOPSIS +usage: tcc [options] [@var{infile1} @var{infile2}@dots{}] [@option{-run} @var{infile} @var{args}@dots{}] +@c man end +@end example + +@noindent +@c man begin DESCRIPTION +TCC options are a very much like gcc options. The main difference is that TCC +can also execute directly the resulting program and give it runtime +arguments. + +Here are some examples to understand the logic: + +@table @code +@item @samp{tcc -run a.c} +Compile @file{a.c} and execute it directly + +@item @samp{tcc -run a.c arg1} +Compile a.c and execute it directly. arg1 is given as first argument to +the @code{main()} of a.c. + +@item @samp{tcc a.c -run b.c arg1} +Compile @file{a.c} and @file{b.c}, link them together and execute them. arg1 is given +as first argument to the @code{main()} of the resulting program. +@ignore +Because multiple C files are specified, @option{--} are necessary to clearly +separate the program arguments from the TCC options. +@end ignore + +@item @samp{tcc -o myprog a.c b.c} +Compile @file{a.c} and @file{b.c}, link them and generate the executable @file{myprog}. + +@item @samp{tcc -o myprog a.o b.o} +link @file{a.o} and @file{b.o} together and generate the executable @file{myprog}. + +@item @samp{tcc -c a.c} +Compile @file{a.c} and generate object file @file{a.o}. + +@item @samp{tcc -c asmfile.S} +Preprocess with C preprocess and assemble @file{asmfile.S} and generate +object file @file{asmfile.o}. + +@item @samp{tcc -c asmfile.s} +Assemble (but not preprocess) @file{asmfile.s} and generate object file +@file{asmfile.o}. + +@item @samp{tcc -r -o ab.o a.c b.c} +Compile @file{a.c} and @file{b.c}, link them together and generate the object file @file{ab.o}. + +@end table + +Scripting: + +TCC can be invoked from @emph{scripts}, just as shell scripts. You just +need to add @code{#!/usr/local/bin/tcc -run} at the start of your C source: + +@example +#!/usr/local/bin/tcc -run +#include <stdio.h> + +int main() +@{ + printf("Hello World\n"); + return 0; +@} +@end example + +TCC can read C source code from @emph{standard input} when @option{-} is used in +place of @option{infile}. Example: + +@example +echo 'main()@{puts("hello");@}' | tcc -run - +@end example +@c man end + +@section Option summary + +General Options: + +@c man begin OPTIONS +@table @option +@item -c +Generate an object file. + +@item -o outfile +Put object file, executable, or dll into output file @file{outfile}. + +@item -run source [args...] +Compile file @var{source} and run it with the command line arguments +@var{args}. In order to be able to give more than one argument to a +script, several TCC options can be given @emph{after} the +@option{-run} option, separated by spaces: +@example +tcc "-run -L/usr/X11R6/lib -lX11" ex4.c +@end example +In a script, it gives the following header: +@example +#!/usr/local/bin/tcc -run -L/usr/X11R6/lib -lX11 +@end example + +@item -mfloat-abi (ARM only) +Select the float ABI. Possible values: @code{softfp} and @code{hard} + +@item -dumpversion +Print only the compiler version and nothing else. + +@item -v +Display TCC version. + +@item -vv +Show included files. As sole argument, print search dirs (as below). + +@item -bench +Display compilation statistics. + +@item -print-search-dirs +Print the configured installation directory and a list of library +and include directories tcc will search. + +@end table + +Preprocessor options: + +@table @option +@item -Idir +Specify an additional include path. Include paths are searched in the +order they are specified. + +System include paths are always searched after. The default system +include paths are: @file{/usr/local/include}, @file{/usr/include} +and @file{PREFIX/lib/tcc/include}. (@file{PREFIX} is usually +@file{/usr} or @file{/usr/local}). + +@item -Dsym[=val] +Define preprocessor symbol @samp{sym} to +val. If val is not present, its value is @samp{1}. Function-like macros can +also be defined: @option{-DF(a)=a+1} + +@item -Usym +Undefine preprocessor symbol @samp{sym}. +@end table + +Compilation flags: + +Note: each of the following options has a negative form beginning with +@option{-fno-}. + +@table @option +@item -funsigned-char +Let the @code{char} type be unsigned. + +@item -fsigned-char +Let the @code{char} type be signed. + +@item -fno-common +Do not generate common symbols for uninitialized data. + +@item -fleading-underscore +Add a leading underscore at the beginning of each C symbol. + +@item -fms-extensions +Allow a MS C compiler extensions to the language. Curretly this +assume a nested named structure declaration without identifier behave +like an unnamed one. + +@item -fdollars-in-identifiers +Allow a dollars in identifiers + +@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 when using libtcc 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. + +@end table + +Note: GCC options @option{-Ox}, @option{-fx} and @option{-mx} are +ignored. +@c man end + +@c man begin ENVIRONMENT +Environment variables that affect how tcc operates. + +@table @option + +@item CPATH +@item C_INCLUDE_PATH +A colon-separated list of directories searched for include files, +directories given with @option{-I} are searched first. + +@item LIBRARY_PATH +A colon-separated list of directories searched for libraries for the +@option{-l} option, directories given with @option{-L} are searched first. + +@end table + +@c man end + +@ignore + +@setfilename tcc +@settitle Tiny C Compiler + +@c man begin SEEALSO +cpp(1), +gcc(1) +@c man end + +@c man begin AUTHOR +Fabrice Bellard +@c man end + +@end ignore + +@node Clang +@chapter C language support + +@section ANSI C + +TCC implements all the ANSI C standard, including structure bit fields +and floating point numbers (@code{long double}, @code{double}, and +@code{float} fully supported). + +@section ISOC99 extensions + +TCC implements many features of the new C standard: ISO C99. Currently +missing items are: complex and imaginary numbers. + +Currently implemented ISOC99 features: + +@itemize + +@item variable length arrays. + +@item 64 bit @code{long long} types are fully supported. + +@item The boolean type @code{_Bool} is supported. + +@item @code{__func__} is a string variable containing the current +function name. + +@item Variadic macros: @code{__VA_ARGS__} can be used for + function-like macros: +@example + #define dprintf(level, __VA_ARGS__) printf(__VA_ARGS__) +@end example + +@noindent +@code{dprintf} can then be used with a variable number of parameters. + +@item Declarations can appear anywhere in a block (as in C++). + +@item Array and struct/union elements can be initialized in any order by + using designators: +@example + struct @{ int x, y; @} st[10] = @{ [0].x = 1, [0].y = 2 @}; + + int tab[10] = @{ 1, 2, [5] = 5, [9] = 9@}; +@end example + +@item Compound initializers are supported: +@example + int *p = (int [])@{ 1, 2, 3 @}; +@end example +to initialize a pointer pointing to an initialized array. The same +works for structures and strings. + +@item Hexadecimal floating point constants are supported: +@example + double d = 0x1234p10; +@end example + +@noindent +is the same as writing +@example + double d = 4771840.0; +@end example + +@item @code{inline} keyword is ignored. + +@item @code{restrict} keyword is ignored. +@end itemize + +@section GNU C extensions + +TCC implements some GNU C extensions: + +@itemize + +@item array designators can be used without '=': +@example + int a[10] = @{ [0] 1, [5] 2, 3, 4 @}; +@end example + +@item Structure field designators can be a label: +@example + struct @{ int x, y; @} st = @{ x: 1, y: 1@}; +@end example +instead of +@example + struct @{ int x, y; @} st = @{ .x = 1, .y = 1@}; +@end example + +@item @code{\e} is ASCII character 27. + +@item case ranges : ranges can be used in @code{case}s: +@example + switch(a) @{ + case 1 @dots{} 9: + printf("range 1 to 9\n"); + break; + default: + printf("unexpected\n"); + break; + @} +@end example + +@cindex aligned attribute +@cindex packed attribute +@cindex section attribute +@cindex unused attribute +@cindex cdecl attribute +@cindex stdcall attribute +@cindex regparm attribute +@cindex dllexport attribute + +@item The keyword @code{__attribute__} is handled to specify variable or +function attributes. The following attributes are supported: + @itemize + + @item @code{aligned(n)}: align a variable or a structure field to n bytes +(must be a power of two). + + @item @code{packed}: force alignment of a variable or a structure field to + 1. + + @item @code{section(name)}: generate function or data in assembly section +name (name is a string containing the section name) instead of the default +section. + + @item @code{unused}: specify that the variable or the function is unused. + + @item @code{cdecl}: use standard C calling convention (default). + + @item @code{stdcall}: use Pascal-like calling convention. + + @item @code{regparm(n)}: use fast i386 calling convention. @var{n} must be +between 1 and 3. The first @var{n} function parameters are respectively put in +registers @code{%eax}, @code{%edx} and @code{%ecx}. + + @item @code{dllexport}: export function from dll/executable (win32 only) + + @end itemize + +Here are some examples: +@example + int a __attribute__ ((aligned(8), section(".mysection"))); +@end example + +@noindent +align variable @code{a} to 8 bytes and put it in section @code{.mysection}. + +@example + int my_add(int a, int b) __attribute__ ((section(".mycodesection"))) + @{ + return a + b; + @} +@end example + +@noindent +generate function @code{my_add} in section @code{.mycodesection}. + +@item GNU style variadic macros: +@example + #define dprintf(fmt, args@dots{}) printf(fmt, ## args) + + dprintf("no arg\n"); + dprintf("one arg %d\n", 1); +@end example + +@item @code{__FUNCTION__} is interpreted as C99 @code{__func__} +(so it has not exactly the same semantics as string literal GNUC +where it is a string literal). + +@item The @code{__alignof__} keyword can be used as @code{sizeof} +to get the alignment of a type or an expression. + +@item The @code{typeof(x)} returns the type of @code{x}. +@code{x} is an expression or a type. + +@item Computed gotos: @code{&&label} returns a pointer of type +@code{void *} on the goto label @code{label}. @code{goto *expr} can be +used to jump on the pointer resulting from @code{expr}. + +@item Inline assembly with asm instruction: +@cindex inline assembly +@cindex assembly, inline +@cindex __asm__ +@example +static inline void * my_memcpy(void * to, const void * from, size_t n) +@{ +int d0, d1, d2; +__asm__ __volatile__( + "rep ; movsl\n\t" + "testb $2,%b4\n\t" + "je 1f\n\t" + "movsw\n" + "1:\ttestb $1,%b4\n\t" + "je 2f\n\t" + "movsb\n" + "2:" + : "=&c" (d0), "=&D" (d1), "=&S" (d2) + :"0" (n/4), "q" (n),"1" ((long) to),"2" ((long) from) + : "memory"); +return (to); +@} +@end example + +@noindent +@cindex gas +TCC includes its own x86 inline assembler with a @code{gas}-like (GNU +assembler) syntax. No intermediate files are generated. GCC 3.x named +operands are supported. + +@item @code{__builtin_types_compatible_p()} and @code{__builtin_constant_p()} +are supported. + +@item @code{#pragma pack} is supported for win32 compatibility. + +@end itemize + +@section TinyCC extensions + +@itemize + +@item @code{__TINYC__} is a predefined macro to indicate that you use TCC. + +@item @code{#!} at the start of a line is ignored to allow scripting. + +@item Binary digits can be entered (@code{0b101} instead of +@code{5}). + +@item @code{__BOUNDS_CHECKING_ON} is defined if bound checking is activated. + +@end itemize + +@node asm +@chapter TinyCC Assembler + +Since version 0.9.16, TinyCC integrates its own assembler. TinyCC +assembler supports a gas-like syntax (GNU assembler). You can +desactivate assembler support if you want a smaller TinyCC executable +(the C compiler does not rely on the assembler). + +TinyCC Assembler is used to handle files with @file{.S} (C +preprocessed assembler) and @file{.s} extensions. It is also used to +handle the GNU inline assembler with the @code{asm} keyword. + +@section Syntax + +TinyCC Assembler supports most of the gas syntax. The tokens are the +same as C. + +@itemize + +@item C and C++ comments are supported. + +@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 */ +#define VT_LLONG 12 /* 64 bit integer */ +#define VT_LONG 13 /* long integer (NEVER USED as type, only + during parsing) */ +#define VT_BTYPE 0x000f /* mask for basic type */ +#define VT_UNSIGNED 0x0010 /* unsigned type */ +#define VT_ARRAY 0x0020 /* array type (also has VT_PTR) */ +#define VT_VLA 0x20000 /* VLA type (also has VT_PTR and VT_ARRAY) */ +#define VT_BITFIELD 0x0040 /* bitfield modifier */ +#define VT_CONSTANT 0x0800 /* const modifier */ +#define VT_VOLATILE 0x1000 /* volatile modifier */ +#define VT_DEFSIGN 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 active 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}. + +@code{SValue.t} is the type. @code{SValue.r} indicates how the value is +currently stored in the generated code. It is usually a CPU register +index (@code{REG_xxx} constants), but additional values and flags are +defined: + +@example +#define VT_CONST 0x00f0 +#define VT_LLOCAL 0x00f1 +#define VT_LOCAL 0x00f2 +#define VT_CMP 0x00f3 +#define VT_JMP 0x00f4 +#define VT_JMPI 0x00f5 +#define VT_LVAL 0x0100 +#define VT_SYM 0x0200 +#define VT_MUSTCAST 0x0400 +#define VT_MUSTBOUND 0x0800 +#define VT_BOUNDED 0x8000 +#define VT_LVAL_BYTE 0x1000 +#define VT_LVAL_SHORT 0x2000 +#define VT_LVAL_UNSIGNED 0x4000 +#define VT_LVAL_TYPE (VT_LVAL_BYTE | VT_LVAL_SHORT | VT_LVAL_UNSIGNED) +@end example + +@table @code + +@item VT_CONST +indicates that the value is a constant. It is stored in the union +@code{SValue.c}, depending on its type. + +@item VT_LOCAL +indicates a local variable pointer at offset @code{SValue.c.i} in the +stack. + +@item VT_CMP +indicates that the value is actually stored in the CPU flags (i.e. the +value is the consequence of a test). The value is either 0 or 1. The +actual CPU flags used is indicated in @code{SValue.c.i}. + +If any code is generated which destroys the CPU flags, this value MUST be +put in a normal register. + +@item VT_JMP +@itemx VT_JMPI +indicates that the value is the consequence of a conditional jump. For VT_JMP, +it is 1 if the jump is taken, 0 otherwise. For VT_JMPI it is inverted. + +These values are used to compile the @code{||} and @code{&&} logical +operators. + +If any code is generated, this value MUST be put in a normal +register. Otherwise, the generated code won't be executed if the jump is +taken. + +@item VT_LVAL +is a flag indicating that the value is actually an lvalue (left value of +an assignment). It means that the value stored is actually a pointer to +the wanted value. + +Understanding the use @code{VT_LVAL} is very important if you want to +understand how TCC works. + +@item VT_LVAL_BYTE +@itemx VT_LVAL_SHORT +@itemx VT_LVAL_UNSIGNED +if the lvalue has an integer type, then these flags give its real +type. The type alone is not enough in case of cast optimisations. + +@item VT_LLOCAL +is a saved lvalue on the stack. @code{VT_LVAL} must also be set with +@code{VT_LLOCAL}. @code{VT_LLOCAL} can arise when a @code{VT_LVAL} in +a register has to be saved to the stack, or it can come from an +architecture-specific calling convention. + +@item VT_MUSTCAST +indicates that a cast to the value type must be performed if the value +is used (lazy casting). + +@item VT_SYM +indicates that the symbol @code{SValue.sym} must be added to the constant. + +@item VT_MUSTBOUND +@itemx VT_BOUNDED +are only used for optional bound checking. + +@end table + +@subsection Manipulating the value stack +@cindex value stack + +@code{vsetc()} and @code{vset()} pushes a new value on the value +stack. If the previous @var{vtop} was stored in a very unsafe place(for +example in the CPU flags), then some code is generated to put the +previous @var{vtop} in a safe storage. + +@code{vpop()} pops @var{vtop}. In some cases, it also generates cleanup +code (for example if stacked floating point registers are used as on +x86). + +The @code{gv(rc)} function generates code to evaluate @var{vtop} (the +top value of the stack) into registers. @var{rc} selects in which +register class the value should be put. @code{gv()} is the @emph{most +important function} of the code generator. + +@code{gv2()} is the same as @code{gv()} but for the top two stack +entries. + +@subsection CPU dependent code generation +@cindex CPU dependent +See the @file{i386-gen.c} file to have an example. + +@table @code + +@item load() +must generate the code needed to load a stack value into a register. + +@item store() +must generate the code needed to store a register into a stack value +lvalue. + +@item gfunc_start() +@itemx gfunc_param() +@itemx gfunc_call() +should generate a function call + +@item gfunc_prolog() +@itemx gfunc_epilog() +should generate a function prolog/epilog. + +@item gen_opi(op) +must generate the binary integer operation @var{op} on the two top +entries of the stack which are guaranted to contain integer types. + +The result value should be put on the stack. + +@item gen_opf(op) +same as @code{gen_opi()} for floating point operations. The two top +entries of the stack are guaranted to contain floating point values of +same types. + +@item gen_cvt_itof() +integer to floating point conversion. + +@item gen_cvt_ftoi() +floating point to integer conversion. + +@item gen_cvt_ftof() +floating point to floating point of different size conversion. + +@item gen_bounded_ptr_add() +@item gen_bounded_ptr_deref() +are only used for bounds checking. + +@end table + +@section Optimizations done +@cindex optimizations +@cindex constant propagation +@cindex strength reduction +@cindex comparison operators +@cindex caching processor flags +@cindex flags, caching +@cindex jump optimization +Constant propagation is done for all operations. Multiplications and +divisions are optimized to shifts when appropriate. Comparison +operators are optimized by maintaining a special cache for the +processor flags. &&, || and ! are optimized by maintaining a special +'jump target' value. No other jump optimization is currently performed +because it would require to store the code in a more abstract fashion. + +@unnumbered Concept Index +@printindex cp + +@bye + +@c Local variables: +@c fill-column: 78 +@c texinfo-column-for-description: 32 +@c End: diff --git a/docs/texi2pod.pl b/docs/texi2pod.pl new file mode 100644 index 0000000..a8f823f --- /dev/null +++ b/docs/texi2pod.pl @@ -0,0 +1,427 @@ +#! /usr/bin/perl -w + +# Copyright (C) 1999, 2000, 2001 Free Software Foundation, Inc. + +# This file is part of GNU CC. + +# GNU CC is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# GNU CC is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with GNU CC; see the file COPYING. If not, write to +# the Free Software Foundation, 59 Temple Place - Suite 330, +# Boston MA 02111-1307, USA. + +# This does trivial (and I mean _trivial_) conversion of Texinfo +# markup to Perl POD format. It's intended to be used to extract +# something suitable for a manpage from a Texinfo document. + +$output = 0; +$skipping = 0; +%sects = (); +$section = ""; +@icstack = (); +@endwstack = (); +@skstack = (); +@instack = (); +$shift = ""; +%defs = (); +$fnno = 1; +$inf = ""; +$ibase = ""; + +while ($_ = shift) { + if (/^-D(.*)$/) { + if ($1 ne "") { + $flag = $1; + } else { + $flag = shift; + } + $value = ""; + ($flag, $value) = ($flag =~ /^([^=]+)(?:=(.+))?/); + die "no flag specified for -D\n" + unless $flag ne ""; + die "flags may only contain letters, digits, hyphens, dashes and underscores\n" + unless $flag =~ /^[a-zA-Z0-9_-]+$/; + $defs{$flag} = $value; + } elsif (/^-/) { + usage(); + } else { + $in = $_, next unless defined $in; + $out = $_, next unless defined $out; + usage(); + } +} + +if (defined $in) { + $inf = gensym(); + open($inf, "<$in") or die "opening \"$in\": $!\n"; + $ibase = $1 if $in =~ m|^(.+)/[^/]+$|; +} else { + $inf = \*STDIN; +} + +if (defined $out) { + open(STDOUT, ">$out") or die "opening \"$out\": $!\n"; +} + +while(defined $inf) { +while(<$inf>) { + # Certain commands are discarded without further processing. + /^\@(?: + [a-z]+index # @*index: useful only in complete manual + |need # @need: useful only in printed manual + |(?:end\s+)?group # @group .. @end group: ditto + |page # @page: ditto + |node # @node: useful only in .info file + |(?:end\s+)?ifnottex # @ifnottex .. @end ifnottex: use contents + )\b/x and next; + + chomp; + + # Look for filename and title markers. + /^\@setfilename\s+([^.]+)/ and $fn = $1, next; + /^\@settitle\s+([^.]+)/ and $tl = postprocess($1), next; + + # Identify a man title but keep only the one we are interested in. + /^\@c\s+man\s+title\s+([A-Za-z0-9-]+)\s+(.+)/ and do { + if (exists $defs{$1}) { + $fn = $1; + $tl = postprocess($2); + } + next; + }; + + # Look for blocks surrounded by @c man begin SECTION ... @c man end. + # This really oughta be @ifman ... @end ifman and the like, but such + # would require rev'ing all other Texinfo translators. + /^\@c\s+man\s+begin\s+([A-Z]+)\s+([A-Za-z0-9-]+)/ and do { + $output = 1 if exists $defs{$2}; + $sect = $1; + next; + }; + /^\@c\s+man\s+begin\s+([A-Z]+)/ and $sect = $1, $output = 1, next; + /^\@c\s+man\s+end/ and do { + $sects{$sect} = "" unless exists $sects{$sect}; + $sects{$sect} .= postprocess($section); + $section = ""; + $output = 0; + next; + }; + + # handle variables + /^\@set\s+([a-zA-Z0-9_-]+)\s*(.*)$/ and do { + $defs{$1} = $2; + next; + }; + /^\@clear\s+([a-zA-Z0-9_-]+)/ and do { + delete $defs{$1}; + next; + }; + + next unless $output; + + # Discard comments. (Can't do it above, because then we'd never see + # @c man lines.) + /^\@c\b/ and next; + + # End-block handler goes up here because it needs to operate even + # if we are skipping. + /^\@end\s+([a-z]+)/ and do { + # Ignore @end foo, where foo is not an operation which may + # cause us to skip, if we are presently skipping. + my $ended = $1; + next if $skipping && $ended !~ /^(?:ifset|ifclear|ignore|menu|iftex)$/; + + die "\@end $ended without \@$ended at line $.\n" unless defined $endw; + die "\@$endw ended by \@end $ended at line $.\n" unless $ended eq $endw; + + $endw = pop @endwstack; + + if ($ended =~ /^(?:ifset|ifclear|ignore|menu|iftex)$/) { + $skipping = pop @skstack; + next; + } elsif ($ended =~ /^(?:example|smallexample|display)$/) { + $shift = ""; + $_ = ""; # need a paragraph break + } elsif ($ended =~ /^(?:itemize|enumerate|[fv]?table)$/) { + $_ = "\n=back\n"; + $ic = pop @icstack; + } else { + die "unknown command \@end $ended at line $.\n"; + } + }; + + # We must handle commands which can cause skipping even while we + # are skipping, otherwise we will not process nested conditionals + # correctly. + /^\@ifset\s+([a-zA-Z0-9_-]+)/ and do { + push @endwstack, $endw; + push @skstack, $skipping; + $endw = "ifset"; + $skipping = 1 unless exists $defs{$1}; + next; + }; + + /^\@ifclear\s+([a-zA-Z0-9_-]+)/ and do { + push @endwstack, $endw; + push @skstack, $skipping; + $endw = "ifclear"; + $skipping = 1 if exists $defs{$1}; + next; + }; + + /^\@(ignore|menu|iftex)\b/ and do { + push @endwstack, $endw; + push @skstack, $skipping; + $endw = $1; + $skipping = 1; + next; + }; + + next if $skipping; + + # Character entities. First the ones that can be replaced by raw text + # or discarded outright: + s/\@copyright\{\}/(c)/g; + s/\@dots\{\}/.../g; + s/\@enddots\{\}/..../g; + s/\@([.!? ])/$1/g; + s/\@[:-]//g; + s/\@bullet(?:\{\})?/*/g; + s/\@TeX\{\}/TeX/g; + s/\@pounds\{\}/\#/g; + s/\@minus(?:\{\})?/-/g; + s/\\,/,/g; + + # Now the ones that have to be replaced by special escapes + # (which will be turned back into text by unmunge()) + s/&/&/g; + s/\@\{/{/g; + s/\@\}/}/g; + s/\@\@/&at;/g; + + # Inside a verbatim block, handle @var specially. + if ($shift ne "") { + s/\@var\{([^\}]*)\}/<$1>/g; + } + + # POD doesn't interpret E<> inside a verbatim block. + if ($shift eq "") { + s/</</g; + s/>/>/g; + } else { + s/</</g; + s/>/>/g; + } + + # Single line command handlers. + + /^\@include\s+(.+)$/ and do { + push @instack, $inf; + $inf = gensym(); + + # Try cwd and $ibase. + open($inf, "<" . $1) + or open($inf, "<" . $ibase . "/" . $1) + or die "cannot open $1 or $ibase/$1: $!\n"; + next; + }; + + /^\@(?:section|unnumbered|unnumberedsec|center)\s+(.+)$/ + and $_ = "\n=head2 $1\n"; + /^\@subsection\s+(.+)$/ + and $_ = "\n=head3 $1\n"; + + # Block command handlers: + /^\@itemize\s+(\@[a-z]+|\*|-)/ and do { + push @endwstack, $endw; + push @icstack, $ic; + $ic = $1; + $_ = "\n=over 4\n"; + $endw = "itemize"; + }; + + /^\@enumerate(?:\s+([a-zA-Z0-9]+))?/ and do { + push @endwstack, $endw; + push @icstack, $ic; + if (defined $1) { + $ic = $1 . "."; + } else { + $ic = "1."; + } + $_ = "\n=over 4\n"; + $endw = "enumerate"; + }; + + /^\@([fv]?table)\s+(\@[a-z]+)/ and do { + push @endwstack, $endw; + push @icstack, $ic; + $endw = $1; + $ic = $2; + $ic =~ s/\@(?:samp|strong|key|gcctabopt|option|env)/B/; + $ic =~ s/\@(?:code|kbd)/C/; + $ic =~ s/\@(?:dfn|var|emph|cite|i)/I/; + $ic =~ s/\@(?:file)/F/; + $_ = "\n=over 4\n"; + }; + + /^\@((?:small)?example|display)/ and do { + push @endwstack, $endw; + $endw = $1; + $shift = "\t"; + $_ = ""; # need a paragraph break + }; + + /^\@itemx?\s*(.+)?$/ and do { + if (defined $1) { + # Entity escapes prevent munging by the <> processing below. + $_ = "\n=item $ic\<$1\>\n"; + } else { + $_ = "\n=item $ic\n"; + $ic =~ y/A-Ya-y/B-Zb-z/; + $ic =~ s/(\d+)/$1 + 1/eg; + } + }; + + $section .= $shift.$_."\n"; +} +# End of current file. +close($inf); +$inf = pop @instack; +} + +die "No filename or title\n" unless defined $fn && defined $tl; + +$sects{NAME} = "$fn \- $tl\n"; +$sects{FOOTNOTES} .= "=back\n" if exists $sects{FOOTNOTES}; + +for $sect (qw(NAME SYNOPSIS DESCRIPTION OPTIONS ENVIRONMENT FILES + BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) { + if(exists $sects{$sect}) { + $head = $sect; + $head =~ s/SEEALSO/SEE ALSO/; + print "=head1 $head\n\n"; + print scalar unmunge ($sects{$sect}); + print "\n"; + } +} + +sub usage +{ + die "usage: $0 [-D toggle...] [infile [outfile]]\n"; +} + +sub postprocess +{ + local $_ = $_[0]; + + # @value{foo} is replaced by whatever 'foo' is defined as. + while (m/(\@value\{([a-zA-Z0-9_-]+)\})/g) { + if (! exists $defs{$2}) { + print STDERR "Option $2 not defined\n"; + s/\Q$1\E//; + } else { + $value = $defs{$2}; + s/\Q$1\E/$value/; + } + } + + # Formatting commands. + # Temporary escape for @r. + s/\@r\{([^\}]*)\}/R<$1>/g; + s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g; + s/\@(?:code|kbd)\{([^\}]*)\}/C<$1>/g; + s/\@(?:gccoptlist|samp|strong|key|option|env|command|b)\{([^\}]*)\}/B<$1>/g; + s/\@sc\{([^\}]*)\}/\U$1/g; + s/\@file\{([^\}]*)\}/F<$1>/g; + s/\@w\{([^\}]*)\}/S<$1>/g; + s/\@(?:dmn|math)\{([^\}]*)\}/$1/g; + + # Cross references are thrown away, as are @noindent and @refill. + # (@noindent is impossible in .pod, and @refill is unnecessary.) + # @* is also impossible in .pod; we discard it and any newline that + # follows it. Similarly, our macro @gol must be discarded. + + s/\(?\@xref\{(?:[^\}]*)\}(?:[^.<]|(?:<[^<>]*>))*\.\)?//g; + s/\s+\(\@pxref\{(?:[^\}]*)\}\)//g; + s/;\s+\@pxref\{(?:[^\}]*)\}//g; + s/\@noindent\s*//g; + s/\@refill//g; + s/\@gol//g; + s/\@\*\s*\n?//g; + + # @uref can take one, two, or three arguments, with different + # semantics each time. @url and @email are just like @uref with + # one argument, for our purposes. + s/\@(?:uref|url|email)\{([^\},]*)\}/<B<$1>>/g; + s/\@uref\{([^\},]*),([^\},]*)\}/$2 (C<$1>)/g; + s/\@uref\{([^\},]*),([^\},]*),([^\},]*)\}/$3/g; + + # Turn B<blah I<blah> blah> into B<blah> I<blah> B<blah> to + # match Texinfo semantics of @emph inside @samp. Also handle @r + # inside bold. + s/</</g; + s/>/>/g; + 1 while s/B<((?:[^<>]|I<[^<>]*>)*)R<([^>]*)>/B<$1>${2}B</g; + 1 while (s/B<([^<>]*)I<([^>]+)>/B<$1>I<$2>B</g); + 1 while (s/I<([^<>]*)B<([^>]+)>/I<$1>B<$2>I</g); + s/[BI]<>//g; + s/([BI])<(\s+)([^>]+)>/$2$1<$3>/g; + s/([BI])<([^>]+?)(\s+)>/$1<$2>$3/g; + + # Extract footnotes. This has to be done after all other + # processing because otherwise the regexp will choke on formatting + # inside @footnote. + while (/\@footnote/g) { + s/\@footnote\{([^\}]+)\}/[$fnno]/; + add_footnote($1, $fnno); + $fnno++; + } + + return $_; +} + +sub unmunge +{ + # Replace escaped symbols with their equivalents. + local $_ = $_[0]; + + s/</E<lt>/g; + s/>/E<gt>/g; + s/{/\{/g; + s/}/\}/g; + s/&at;/\@/g; + s/&/&/g; + return $_; +} + +sub add_footnote +{ + unless (exists $sects{FOOTNOTES}) { + $sects{FOOTNOTES} = "\n=over 4\n\n"; + } + + $sects{FOOTNOTES} .= "=item $fnno.\n\n"; $fnno++; + $sects{FOOTNOTES} .= $_[0]; + $sects{FOOTNOTES} .= "\n\n"; +} + +# stolen from Symbol.pm +{ + my $genseq = 0; + sub gensym + { + my $name = "GEN" . $genseq++; + my $ref = \*{$name}; + delete $::{$name}; + return $ref; + } +} |