Mercurial > hg > index.cgi

annotate lwcc/README.txt @ 569:37014b2935bf lwtools-4.22

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bump version in preparation for release
author William Astle <lost@l-w.ca>
date Fri, 22 Dec 2023 21:03:18 -0700
parents 9e342c4e4b66
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
286
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
1 This is the lwcc C compiler for lwtools. It was written using various other
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
2 C compilers as guides. Special thanks to the developers of the PCC compiler.
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
3 While none of the actual code from PCC was actually used, much of compiler
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
4 itself served as a template for creating lwcc.
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
5
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
6
307
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
7 LIMITATIONS AND DESIGN CHOICES
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
8 ==============================
286
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
9
307
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
10 The direct interface to both the compiler proper and the preprocessor is
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
11 specifically undefined. Indeed, the preprocessor may, in fact, not be a
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
12 separate program at all. Relying on the specific format of the output of the
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
13 preprocessor is specifically forbidden even though it is possible to obtain
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
14 preprocessed output from the compiler driver. This is provided for debugging
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
15 purposes only.
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
16
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
17 The preprocessor supports variadic macros. It also supports stringification,
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
18 and token concatenation but only within a macro expansion. There are
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
19 examples online that use the construct "#__LINE__" to get a string version
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
20 of the current line number.
286
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
21
307
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
22 The preprocessor defaults to ignoring trigraphs because they are basically a
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
23 stupid idea on any current system. They have their place for systems where
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
24 creating the nine characters specified by the trigraphs is very difficult or
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
25 impossible. It is possible, however, to instruct the preprocessor to decode
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
26 trigraph sequences.
292
40ecbd5da481 Part one of the C preprocessor
William Astle <lost@l-w.ca>
parents: 290
diff changeset
27
307
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
28 The nonstandard "#pragma once" feature is not supported at all. The effect
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
29 is easily accomplished using standard macros and conditionals. It is,
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
30 therefore, unneeded complexity.
292
40ecbd5da481 Part one of the C preprocessor
William Astle <lost@l-w.ca>
parents: 290
diff changeset
31
307
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
32 The nonstandard idea of preprocessor assertions is also completely
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
33 unsupported. It is just as easy to test predefined macros and such tests are
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
34 much more portable.
286
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
35
307
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
36 The preprocessor supports __LINE__, __FILE__, __DATE__, and __TIME__. The
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
37 compiler itself supports __func__ as a predefined string constant if
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
38 encountered because there is no way for the preprocessor to determine what
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
39 function it occurs within. The preprocessor does not define __STDC__,
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
40 __STDC_VERSION__, or __STDC_HOSTED__. I have seen no truly useful purpose
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
41 for these and since lwcc does not, at this time, conform to any known C
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
42 standard, it would be incorrect to define the first two.
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
43
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
44 The compiler driver may define additional macros depending on its idea of
9e342c4e4b66 Added support for __LINE__, __FILE__, __DATE__, and __TIME__
William Astle <lost@l-w.ca>
parents: 292
diff changeset
45 the context.
286
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
46
290
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
47
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
48 RUNTIME INFORMATION
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
49 ===================
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
50
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
51 The compiler driver has a built in base directory where it searches for its
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
52 various components as needed. In the discussion below, BASEDIR stands for
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
53 that directory.
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
54
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
55 BASEDIR may be specified by the -B option to the driver. Care must be taken
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
56 when doing so, however, because specifying an invalid -B will cause the
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
57 compiler to fail completely. It will completely override the built in search
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
58 paths for the compiler provided files and programs.
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
59
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
60 Because BASEDIR is part of the actual compiler, it is not affected by
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
61 --sysroot or -isysroot options.
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
62
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
63 If BASEDIR does not exist, compiler component programs will be searched for
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
64 in the standard execution paths. This may lead to incorrect results so it is
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
65 important to make certain that the specified BASEDIR exists.
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
66
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
67 If -B is not specified, the default BASEDIR is
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
68 $(PREFIX)/lib/lwcc/$(VERSION)/ where PREFIX is the build prefix from the
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
69 Makefile and VERSION is the lwtools version.
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
70
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
71 The contents of BASEDIR are as follows:
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
72
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
73 BASEDIR/bin
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
74
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
75 Various binaries for the parts of the compiler system. Notably, this
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
76 includes the preprocessor and compiler proper. The specific names and
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
77 contents of this directory cannot be relied upon and these programs should
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
78 not be called directly. Ever. Don't do it.
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
79
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
80
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
81 BASEDIR/lib
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
82
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
83 This directory contains various libraries that provide support for any
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
84 portion of the compiler's output. The driver will arrange to pass the
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
85 appropriate arguments to the linker to include these as required.
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
86
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
87 The most notable file in this directory is liblwcc.a wich contains the
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
88 support routines for the compiler's code generation. Depending on ABI and
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
89 code generation options supported, there may be multiple versions of
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
90 liblwcc.a. The driver will arrange for the correct one to be referenced.
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
91
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
92
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
93 BASEDIR/include
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
94
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
95 This directory contains any C header files that the compiler provides.
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
96 Notably, this includes stdint.h, stdarg.h, and setjmp.h as these are
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
97 specific to the compiler. The driver will arrange for this directory to be
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
98 searched prior to the standard system directories so that these files will
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
99 override any present in those directories.
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
100