Mercurial > hg > index.cgi

annotate lwcc/README.txt @ 304:d85d173ba120 ccdev

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Checkpoint lwcc development - preprocessor is runnable but nonfunctional The preprocessor is currently runnable but doesn't actually do anything useful. This is just a checkpoint.
author William Astle <lost@l-w.ca>
date Tue, 17 Sep 2013 19:33:41 -0600
parents 40ecbd5da481
children 9e342c4e4b66
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 This directory is arranged as follows:
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
7
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
8 driver/
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
9
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
10 This contains the source for the front end driver program which will be
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
11 called "lwcc" and is the public face of the compiler. The lwcc program
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
12 itself provides various options that are largely compatible with unix C
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
13 compilers like gcc. It should be noted that the internal interface between
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
14 the lwcc driver and its back end programs (the preprocessor and compiler
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
15 proper) is unspecified and subject to change without notice. The assembler
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
16 and linker (lwasm, lwlink) do have defined public interfaces are are not
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
17 likely to change substantially.
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
18
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
19
292
40ecbd5da481 Part one of the C preprocessor
William Astle <lost@l-w.ca>
parents: 290
diff changeset
20 cpp/
40ecbd5da481 Part one of the C preprocessor
William Astle <lost@l-w.ca>
parents: 290
diff changeset
21
40ecbd5da481 Part one of the C preprocessor
William Astle <lost@l-w.ca>
parents: 290
diff changeset
22 This is the actual C preprocessor. Its specific interface is deliberately
40ecbd5da481 Part one of the C preprocessor
William Astle <lost@l-w.ca>
parents: 290
diff changeset
23 undocumented. Do not call it directly. Ever. Just don't. Bad Things(tm) will
40ecbd5da481 Part one of the C preprocessor
William Astle <lost@l-w.ca>
parents: 290
diff changeset
24 happen if you do.
40ecbd5da481 Part one of the C preprocessor
William Astle <lost@l-w.ca>
parents: 290
diff changeset
25
40ecbd5da481 Part one of the C preprocessor
William Astle <lost@l-w.ca>
parents: 290
diff changeset
26
286
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
27 liblwcc/
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
28
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
29 This contains any runtime libraries the compiler needs to support its
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
30 output. This is usually assembly routines to support complex operations not
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
31 directly supported by the CPU instruction set.
d9631a9a5b61 Set up for lwcc development with README file.
William Astle <lost@l-w.ca>
parents:
diff changeset
32
290
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
33
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
34 RUNTIME INFORMATION
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
35 ===================
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
36
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
37 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
38 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
39 that directory.
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
40
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
41 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
42 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
43 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
44 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
45
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
46 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
47 --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
48
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
49 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
50 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
51 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
52
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
53 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
54 $(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
55 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
56
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
57 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
58
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
59 BASEDIR/bin
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
60
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
61 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
62 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
63 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
64 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
65
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 BASEDIR/lib
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
68
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
69 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
70 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
71 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
72
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
73 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
74 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
75 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
76 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
77
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
78
c648fc4bd006 Updated lwcc README with info on the runtime support files
William Astle <lost@l-w.ca>
parents: 286
diff changeset
79 BASEDIR/include
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 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
82 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
83 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
84 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
85 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
86