Mercurial > hg > index.cgi

comparison lwcc/README.txt @ 495:5b8871fd7503

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merged previous lwcc development branch into mainline.
author William Astle <lost@l-w.ca>
date Mon, 05 Aug 2019 21:27:09 -0600
parents 9e342c4e4b66
children
comparison
equal deleted inserted replaced
493:6073f4a33475 495:5b8871fd7503
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.
5
6
7 LIMITATIONS AND DESIGN CHOICES
8 ==============================
9
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.
16
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.
21
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.
27
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.
31
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.
35
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.
43
44 The compiler driver may define additional macros depending on its idea of
45 the context.
46
47
48 RUNTIME INFORMATION
49 ===================
50
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.
54
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.
59
60 Because BASEDIR is part of the actual compiler, it is not affected by
61 --sysroot or -isysroot options.
62
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.
66
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.
70
71 The contents of BASEDIR are as follows:
72
73 BASEDIR/bin
74
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.
79
80
81 BASEDIR/lib
82
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.
86
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.
91
92
93 BASEDIR/include
94
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.
100