Update README
[xonotic/gmqcc.git] / README
1 This is my work in progress Quake C compiler. There are very few _good_ QC
2 compilers out there on the internet that can be used in the opensource
3 community.  There are a lot of mediocre compilers, but no one wants those.
4 This is the solution for that, for once a proper Quake C compiler that is
5 capable of doing proper optimization.  The design so far of this compiler
6 is basic, because it doesn't actually compile code yet.
7
8 gmqcc.h
9         This is the common header with all definitions, structures, and
10         constants for everything.
11
12 error.c
13         This is the error subsystem, this handles the output of good detailed
14         error messages (not currently, but will), with colors and such.
15         
16 lex.c
17         This is the lexer, a very small basic step-seek lexer that can be easily
18         changed to add new tokens, very retargetable.
19         
20 main.c
21         This is the core compiler entry, handles switches (will) to toggle on
22         and off certian compiler features.
23         
24 parse.c
25         This is the parser which goes over all tokens and generates a parse tree
26         and check for syntax correctness.
27         
28 typedef.c
29         This is the typedef system, this is a seperate file because it's a lot more
30         complicated than it sounds.  This handles all typedefs, and even recrusive
31         typedefs.
32         
33 util.c
34         These are utilities for the compiler, some things in here include a
35         allocator used for debugging, and some string functions.
36         
37 assembler.c
38         This implements support for assembling Quake assembler (which doesn't
39         actually exist untill now: documentation of the Quake assembler is below.
40         This also implements (will) inline assembly for the C compiler.
41         
42 README
43         This is the file you're currently reading
44         
45 Makefile
46         The makefile, when sources are added you should add them to the SRC=
47         line otherwise the build will not pick it up.  Trivial stuff, small
48         easy to manage makefile, no need to complicate it.
49         Some targets:
50                 #make gmqcc
51                         Builds gmqcc, creating a gmqcc binary file in the current
52                         directory as the makefile.
53                         
54                 #make clean
55                         Cleans the build files left behind by a previous build
56
57 ////////////////////////////////////////////////////////////////////////
58 ///////////////////// Quake Assembler Documentation ////////////////////
59 ////////////////////////////////////////////////////////////////////////
60 Quake assembler is quite simple: it's just an annotated version of the binary
61 produced by any existing QuakeC compiler, but made cleaner to use, (so that
62 the location of various globals or strings are not required to be known).
63
64 Constants:
65         Using one of the following valid constant typenames, you can declare
66         a constant {FLOAT,VECTOR,FUNCTION,FIELD,ENTITY}, all typenames are
67         proceeded by a colon, and the name (white space doesn't matter).
68         
69         Examples:
70                 FLOAT: foo 1
71                 VECTOR: bar 1 2 1
72                 STRING: hello "hello world"
73                 
74 Comments:
75         Commenting assembly requires the use of either # or ; on the line
76         that you'd like to be ignored by the assembler. You can only comment
77         blank lines, and not lines assembly already exists on.
78         
79 Functions:
80         Creating functions is the same as declaring a constant, simply use
81         FUNCTION followed by a colon, and the name (white space doesn't matter)
82         and start the statements for that function on the line after it
83         
84         Examples:
85                 FLOAT: foo 1
86                 FLOAT: bar 2
87                 FUNCTION: test1
88                         ADD foo, bar, OFS_RETURN
89                         RETURN
90                         
91                 FUNCTION: test2
92                         CALL0 test1
93                         DONE
94                         
95 Internal:
96         The Quake engine provides some internal functions such as print, to
97         access these you first must declare them and their names. To do this
98         you create a FUNCTION as you currently do. Adding a $ followed by the
99         number of the engine builtin will bind it to that builtin.
100         
101         Examples:
102                 FUNCTION: print $4
103                 FUNCTION: error $3
104
105 Misc:
106         There are some rules as to what your identifiers can be for functions
107         and constants.  All indentifiers mustn't begin with a numeric digit,
108         identifiers cannot include spaces, or tabs; they cannot contain symbols,
109         and they cannot exceed 32768 characters. Identifiers cannot be all 
110         capitalized either, as all capatilized identifiers are reserved by the
111         assembler.
112         
113         Numeric constants cannot contain special notation such as `1-e10`, all
114         numeric constants have to be numeric, they can contain decmial points
115         and signs (+, -) however.
116         
117         Constants cannot be assigned values of other constants, their value must
118         be fully expressed inspot of the declration.
119         
120         No two identifiers can be the same name, this applies for variables allocated
121         inside a function scope (despite it being considered local).