view lwcc/README.txt @ 314:a3e277c58df9

Checkpoint parser development for lwcc

Beginning of lemon based parser for C including all the infrastructure for
calling the lemon generated parser. This requires a translation layer from
the preprocessor token numbers to the lemon parser token numbers due to the
fact that lemon wants to control the token numbers. Eventually when the
lemon parser gets replaced with a hand crafted recursive descent parser,
this translation will no longer be required. However, in the interest of
getting things working sooner rather than later, using something like lemon
is beneficial.
author William Astle <lost@l-w.ca>
date Sun Nov 17 11:59:36 2013 -0700 (2013-11-17)
parents 40ecbd5da481
line source
1 This is the lwcc C compiler for lwtools. It was written using various other
2 C compilers as guides. Special thanks to the developers of the PCC compiler.
3 While none of the actual code from PCC was actually used, much of compiler
4 itself served as a template for creating lwcc.
8 ==============================
10 The direct interface to both the compiler proper and the preprocessor is
11 specifically undefined. Indeed, the preprocessor may, in fact, not be a
12 separate program at all. Relying on the specific format of the output of the
13 preprocessor is specifically forbidden even though it is possible to obtain
14 preprocessed output from the compiler driver. This is provided for debugging
15 purposes only.
17 The preprocessor supports variadic macros. It also supports stringification,
18 and token concatenation but only within a macro expansion. There are
19 examples online that use the construct "#__LINE__" to get a string version
20 of the current line number.
22 The preprocessor defaults to ignoring trigraphs because they are basically a
23 stupid idea on any current system. They have their place for systems where
24 creating the nine characters specified by the trigraphs is very difficult or
25 impossible. It is possible, however, to instruct the preprocessor to decode
26 trigraph sequences.
28 The nonstandard "#pragma once" feature is not supported at all. The effect
29 is easily accomplished using standard macros and conditionals. It is,
30 therefore, unneeded complexity.
32 The nonstandard idea of preprocessor assertions is also completely
33 unsupported. It is just as easy to test predefined macros and such tests are
34 much more portable.
36 The preprocessor supports __LINE__, __FILE__, __DATE__, and __TIME__. The
37 compiler itself supports __func__ as a predefined string constant if
38 encountered because there is no way for the preprocessor to determine what
39 function it occurs within. The preprocessor does not define __STDC__,
40 __STDC_VERSION__, or __STDC_HOSTED__. I have seen no truly useful purpose
41 for these and since lwcc does not, at this time, conform to any known C
42 standard, it would be incorrect to define the first two.
44 The compiler driver may define additional macros depending on its idea of
45 the context.
49 ===================
51 The compiler driver has a built in base directory where it searches for its
52 various components as needed. In the discussion below, BASEDIR stands for
53 that directory.
55 BASEDIR may be specified by the -B option to the driver. Care must be taken
56 when doing so, however, because specifying an invalid -B will cause the
57 compiler to fail completely. It will completely override the built in search
58 paths for the compiler provided files and programs.
60 Because BASEDIR is part of the actual compiler, it is not affected by
61 --sysroot or -isysroot options.
63 If BASEDIR does not exist, compiler component programs will be searched for
64 in the standard execution paths. This may lead to incorrect results so it is
65 important to make certain that the specified BASEDIR exists.
67 If -B is not specified, the default BASEDIR is
68 $(PREFIX)/lib/lwcc/$(VERSION)/ where PREFIX is the build prefix from the
69 Makefile and VERSION is the lwtools version.
71 The contents of BASEDIR are as follows:
73 BASEDIR/bin
75 Various binaries for the parts of the compiler system. Notably, this
76 includes the preprocessor and compiler proper. The specific names and
77 contents of this directory cannot be relied upon and these programs should
78 not be called directly. Ever. Don't do it.
81 BASEDIR/lib
83 This directory contains various libraries that provide support for any
84 portion of the compiler's output. The driver will arrange to pass the
85 appropriate arguments to the linker to include these as required.
87 The most notable file in this directory is liblwcc.a wich contains the
88 support routines for the compiler's code generation. Depending on ABI and
89 code generation options supported, there may be multiple versions of
90 liblwcc.a. The driver will arrange for the correct one to be referenced.
93 BASEDIR/include
95 This directory contains any C header files that the compiler provides.
96 Notably, this includes stdint.h, stdarg.h, and setjmp.h as these are
97 specific to the compiler. The driver will arrange for this directory to be
98 searched prior to the standard system directories so that these files will
99 override any present in those directories.