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         Examples:
  80                 ; this is allowed
  81                 # as is this
  82                 FLOAT: foo 1 ; this is not allowed
  83                 FLOAT: bar 2 # neither is this
  84
  85 Functions:
  86         Creating functions is the same as declaring a constant, simply use
  87         FUNCTION followed by a colon, and the name (white space doesn't matter)
  88         and start the statements for that function on the line after it
  89
  90         Examples:
  91                 FLOAT: foo 1
  92                 FLOAT: bar 2
  93                 FUNCTION: test1
  94                         ADD foo, bar, OFS_RETURN
  95                         RETURN
  96
  97                 FUNCTION: test2
  98                         CALL0 test1
  99                         DONE
 100
 101 Internal:
 102         The Quake engine provides some internal functions such as print, to
 103         access these you first must declare them and their names. To do this
 104         you create a FUNCTION as you currently do. Adding a $ followed by the
 105         number of the engine builtin (negated).
 106
 107         Examples:
 108                 FUNCTION: print $4
 109                 FUNCTION: error $3
 110
 111 Misc:
 112         There are some rules as to what your identifiers can be for functions
 113         and constants.  All indentifiers mustn't begin with a numeric digit,
 114         identifiers cannot include spaces, or tabs; they cannot contain symbols,
 115         and they cannot exceed 32768 characters. Identifiers cannot be all
 116         capitalized either, as all capatilized identifiers are reserved by the
 117         assembler.
 118
 119         Numeric constants cannot contain special notation such as `1-e10`, all
 120         numeric constants have to be numeric, they can contain decmial points
 121         and signs (+, -) however.
 122
 123         Constants cannot be assigned values of other constants, their value must
 124         be fully expressed inspot of the declartion.
 125
 126         No two identifiers can be the same name, this applies for variables allocated
 127         inside a function scope (despite it being considered local).
 128
 129         There exists one other keyword that is considered sugar, and that
 130         is AUTHOR, this keyword will allow you to speciy the AUTHOR(S) of
 131         the assembly being assembled. The string represented for each usage
 132         of AUTHOR is wrote to the end of the string table. Simaler to the
 133         usage of constants and functions the AUTHOR keyword must be proceeded
 134         by a colon.
 135
 136         Examples:
 137                 AUTHOR: "Dale Weiler"
 138                 AUTHOR: "John Doe"
 139
 140         Colons exist for the sole reason of not having to use spaces after
 141         keyword usage (however spaces are allowed).  To understand the
 142         following examples below are equivlent.
 143
 144         Example 1:
 145                 FLOAT:foo 1
 146         Example 2:
 147                 FLOAT: foo 1
 148         Example 3:
 149                 FLOAT:  foo 2
 150
 151         variable amounts of whitespace is allowed anywhere (as it should be).
 152         think of `:` as a delimiter (which is what it's used for during assembly).
 153
 154 ////////////////////////////////////////////////////////////////////////
 155 /////////////////////// Quake C Documentation //////////////////////////
 156 ////////////////////////////////////////////////////////////////////////
 157 TODO ....