Title    : FrikQCC
Filename : frikqcc.zip
Version  : 2.2
Date     : 5-16-2000
Author   : Ryan "Frika C" Smith
Email    : frika-c@mdqnet.net
Credits  : JP Grossman for qccx 1.0 (This man is a god! Worship him!)
           Lee Smith for proqcc 1.60
           Both for releasing their source under GPL, thanks :)


Description 
-----------

A little less than a month ago, JP Grossman released what I consider a
historic milestone in Quake history: his custom  QuakeC compiler entitled
qccx. My own compiler, released about 3 months earlier, suddenly looked
boring by comparison.

Anyway, I recently got the urge to work on compilers again, and this time I
started from qccx's lead.

*** Improtant ***

This compiler is a modification of JP Grossman's qccx. Everything that qccx
supports, frikqcc does also. I chose not, however, to include JP Grossman's
manual.txt nor his example qc project. You can download those, along with
the original qccx at:

http://elohim.ai.mit.edu/qccx

I recommend that you go download it immediately and read the manual.txt
a few hundered times, or until the room starts spinning and you feel light-
headed. By about that time, you'll have realized how revolutionary qccx is.
After you've recovered, finish reading this readme file, then get coding!

I do not intend to offer support on qccx's features [or those feature's
counterparts in frikqcc]. Manual.txt is all you get, buddy. Live with it.


Features over qccx
==================
* Compiler Warnings
* Labels and Goto
* Break and Continue
* Static variables
* Conditional Expressions
* Decompilation
* New Optimizations
* Misc features


Compiler Warnings
-----------------
Compiler warnings is a pretty novel feature I haven't seen in any other 
QuakeC compiler to date. For the unitiated - warnings are like errors,  only
they aren't "fatal". Meaning, hitting a warning will not cause the compiler
to abort. Warnings, as the name implies, warn you about potentially error
causing situations, or lines of code that could be changed for better
performance.

Most warnings the compiler supports are based on relatively common warnings
in MSVC++. Like MSVC, frikqcc supports 4 warning levels, and an option to
turn warnings off. Lower numbered levels produce fewer warnings, while warning
level 4 will nitpick your code to death. You can specify the warning level
with the command line parameter -warn x, where x ranges from 0 to 4. At 0, no
warnings will be displayed.

At warning level 3 and above, you may see the message "Unreferenced local
variable somevector_x", in this situation the compiler means the vector
"somevector" is not referenced at all within the function. Due to my extreme
laziness, I just let it use the default def name :).

[There aren't any level 4 warnings yet, btw]

Labels and Goto
---------------
In my effort to give you a little more control over program flow, I added
labels and the goto command from C. Unlike C, however, labels are not defined
by a name followed by a colon, but rather a colon then a name. This was done
to make spotting labels a little easier.

Example:

void() main =
{
	if (i == 1)
		goto main_end;
	
	// do some code

	:main_end
	// code to finish up
};


Note that goto need not be restricted to the same function or even the same
.qc file. You can, I believe, jump from anywhere to anywhere in the QC with
this command.


Break and Continue
------------------
These work identically to their C counterparts. break; aborts out of the
current loop, and continue; sends the loop for another pass.


Static Variables
----------------
Frikqcc adds support for local statics. Statics in frikqcc are identical to
local-declared variables, but they are not cleared between instance or
executions of the function. Due to how variables are stored in the progs.dat,
you must declare all statics after all local variables.

Example:

void() main =
{
	local string h;
	static float been_called;

	been_called = been_called + 1;
	bprint("Main has been called ");
	h = ftos(been_called);
	bprint(h);
	bprint("time(s)!\n");
};


Conditional Expressions
-----------------------
Frikqcc supports also C-style conditional expressions in the format:

(condition) ? expression1 : expression2

The operation of this is identical to C. If the condition true, expression1
is used, otherwise, expression2 is used. A simple toggle might be:

self.aflag = self.aflag ? 0 : 1;


Decompilation
-------------
Frikqcc also includes a built-in decompiler, based on ProQCC. I've made some
decent changes to the decompiler, making it output somewhat better looking 
code. In addition, I also 'fixed' proqcc's mishandling of progs in which the
source code was compiled from multiple folders.

Also thanks to Raymond Martineau pointing it out, frikqcc will decompile 
qwprogs.dat files.


New Optimizations
-----------------
JP Grossman's qccx optimizations are an impressive bunch, I must admit. For
my part, I've added three optimizations expanding on the lead of the qccx /Oc
optimization. They are:

/Ol - Eliminate local names
---
The names of local, static and immediates are stripped from the progs.dat
upon write time. This saves some space, and does not affect the usability of
the compiled code.


/On - Eliminate uneeded function names
---
The function names of any function assigned to a built-in or who's first
statement is OP_STATE are removed from the progs.dat. Again, a space
optimization only.


/Of - Eliminate source code file names
---
*Another* space optimization, file names of the source files are not stored
in the compiled progs.

The /O2 option has been expanded to include all of the above.


Misc Features
-------------
* Frikqcc will write an error.log in the source dir of all errors/warnings
  encountered during the compile.
* Frikqcc will wait for any key to be pressed before closing when run with
  no parameters. (Note: the command line parameters -nopause and -pause can
  be used to override this behavior, one way or the other)
* The semicolon on the end of functions is now optional.
* The keyword "local" is also now optional. "float x;" inside a function is
  equivalent to the code "local float x;"

Copyright and Distribution Permissions
--------------------------------------
qccx is Copyrighted (c) 2000 by JP Grossman
ProQCC is Copyrighted (c) 1997-2000 Lee Smith
FrikQCC specific additions are Copyrighted (c) 2000 by Ryan Smith

Frikqcc is released under the GNU General Public License. Please read 
gnu.txt.  (Taking from JP Grossman's readme) John Carmack summarized the
GPL as follows:

"The code is all licensed under the terms of the GPL (gnu public license).  
You should read the entire license, but the gist of it is that you can do 
anything you want with the code, including sell your new version.  The catch 
is that if you distribute new binary versions, you are required to make the 
entire source code available for free to everyone."

The source code is included with this archive. Keep in mind, I haven't been
coding in C for very long, and I imagine that to more seasoned C coders
my code must look horrible. Please, if you have anything in the way of
suggestions, improvements, or ideas, email me at frikac@mdqnet.net


Availability
------------
This utility is available from the following places:

FrikBot homepage at http://www.mdqnet.net/frikbot/
