OXCC.TXT Version: 1.433 -- preliminary 5 Nov 1995 by Norman D. Culver

    OXCC is a multipass interpreting C compiler with numerous language
    extensions (see c.grm).

    OXCC generates output in an Architecture Neutral Format (ANF).
	Sample backends are provided to guide the programmer in dealing with
	ANF and in writing additional backends for a specific purpose.

	The builtin interpreter provides for a great deal of flexibility
	but it does make the compiler a memory hog. The entire file under
	compilation is stored in memory as an Abstract Syntax Tree (AST).
	The AST can be printed to stdout with the -a option.

	Language extensions have been inspired by GCC, MSC, and Watcom C.
	OXCC is designed to produce 16 bit, 32 bit, 64 bit, segmented and 
	flat model code for any target architecture and operating system.

	OXCC can regenerate C source code after interpreting some or all of 
	its' input. Source regeneration properly handles `malloced' data
	containing pointers. The regenerated source code can be `shrouded'.
	Regenerated source files have the suffix .cr .

	The builtin interpreter can be run in fast or slow mode. Slow mode
	maintains elaborate pointer and initialization information which
	often is the only way to catch a subtle runtime bug.

    The compiler and include files are located in the file `oxcc.cff'. It
    is run from the command line by the skeleton program `oxcc.exe'
    (see skel.doc). If no switches are enabled, OXCC merely checks the
    input file(s) for errors.

	OXCC is reentrant; a set of C calls and a set of class based calls
	are provided. Multiple instances of OXCC can be run simultaneously.
	A program being compiled by OXCC can run OXCC as a subroutine.
	The program under compilation can gain access to the AST and
	symbol tables which describe it by using the calls __builtin_iv() and
	__builtin_root(). See: toxcc.c

Usage: oxcc [-adoqrstuwABDEFGHILMOPRSTWY(] file...
   -a == print ast                   -s == print symbol table
   -t == print runtimes              -u == print memory usage
   -r == run the code                -f == if run code, go fast
   -L == produce listing             -E == preprocess only
   -S == shrouded source output      -T == trace lines while interpreting
   -P == Parse only
   "-(args for interpreted main" 
   -dn == enable debug output, 1=parser 2=lexer 3=both
   -q == suppress printing gratuitous info
   -o outfile == name of output file, default is first infile
   -A == ansi_mode (suppress extensions, not fully implemented)
   -W == if run code and not fast mode, warn about address problems
   -w == suppress compiler warnings
   -R func == if run code, start at function `func'
   -Ipath == include path for the C preprocessor
   -Ddef == define something for the C preprocssor
   -Gx == generate output in format `x' (abdnmrs)
   -Ox == generate output for operating system `x' (dDwWCNoOUL)
   -Hx == generate output for hardware type `x' (iIPDHmM)
   -Bx == generate output for debugger `x' (vwbgd)
   -Fx == generate object file format `x' (oOPWBace)
   -Yx == generate assembler format `x' (ugmt)
   -Mx == use memory model `x' (tsmlchx)

OUTPUT OPTIONS
    -Gs   regenerate source (output file has .cr suffix)
    -SGs  regenerate shrouded source (output file has .cr suffix)
    -Gb   generate bytecodes (calls oxccb, output file has .byt suffix)
    -LGb  generate bytecode listing (calls oxccb, output file has .lst suffix)
    -Ga   generate assembler output (calls oxccaH, where H is hardware type)
    -Gd   generate readable ANF code (output file has .dbg suffix)
    -Gm   generate machine code (calls oxccmH, where H is hardware type)
    -Gn   generate ANF code (output file has .anf suffix)
    -Gr   generate RIP code (calls oxccr, output file has .rip suffix)

	(see oxanf.doc, oxanf.h)
    -Ox   placed in header slot `target_os'         default `D' DOS32PLAT
    -Hx   placed in header slot `target_hardware'   default `I' INTEL8632
    -Bx   placed in header slot `target_debugger'   default  0  NONE
    -Fx   placed in header slot `obj_format'        default `a' AOUTFORMAT
    -Yx   placed in header slot `target_assembler'  default `g' GAS
    -Mx   placed in header slot `memory_model'      default `x' MODFLAT


INCOMPATIBILITIES

    FUNCTION DECLARATIONS
    OXCC, being a multipass compiler, always chooses the `best' declaration
    for a function. The old style practice of hiding function declarations
    with a declaration containing an unknown number of args (commonly used
    by some programmers) just will not work. At the very least you
    will get a warning if a subroutine is called with arguments imcommensurate
    with the `best' declaration. OXCC will not assume that the declaration
    of an undeclared function `func' is `int func()', you must explicitly
    declare all functions.


LANGUAGE EXTENSIONS

    RUNTIME INTERPRETATION
    The -r switch will cause OXCC to interpret the AST if it can find
    a function named `main' or failing that a function with the base name
    of the input file e.g. test32.c with a function named `test32'.
    The user can specify a unique starting function with the -R switch.
    Arguments can be passed to the starting function by using the -( switch
    providing the starting function adheres to the argc, argv convention.
    e.g.:
       oxcc -r test32.c "-(23 hello 14 -W"
    Another way to cause runtime interpretation is to call the starting
    function from the right hand side of the last initialized outer variable.
    The only restriction is that the starting function must return a value.


    INTERPRETING OUTER DECLARATIONS INCLUDING INNER STATIC VARIABLES
	OXCC evaluates (interprets) non-constant expressions in outer declarations.
    Anything that can appear in a normal C program can contribute to the value
    that is stored in an initialized variable. Uninitialized variables can 
    become initialized as a side effect of a function call. Two reserved words
    `_ival' and `_ifunc' can be prepended to variables and functions 
    respectively in order to prevent them from appearing in the output.
    e.g.:
        double q = sin(2.0) / cos(4.3);
	    void *ptr = malloc(200);    // interpreted malloc acts like calloc
	    static int x,y;
	    _ifunc int initfunc()      // function `initfunc' will not be output
	    {
		int i;
	        x = 50;    // static variable x is initialized to 50.
	        y = 25;    // static variable y is initialized to 25.
			for(i = 0; i < x; ++i)
				ptr[i] = malloc(y);	// initialize the array of pointers
	        return 0;
	    }
        int startfunc(int z)  // function `startfunc' will appear in output
        {
			x += z;		// static variable x is modified before output
			...
			return 0;
        }
	    _ival int z = initfunc();    // variable `z' will not be output
		char *ary[20] = {[2]=ptr[3], [3]=malloc(x), [18]=malloc(y)};
        _ival int dummy = startfunc(25); // variable `dummy' will not be output


	AUTOMATIC VARIABLES (INNER DECLARATIONS)
    Automatic variables can be initialized with non-constant expressions.
    Static variables mentioned inside functions can be non-constant and
    will be initialized at outer declaration time.
    `alloca' is not a suitable initializer for a static variable inside
    a function, use `malloc'.


    DEFAULT ARGUMENTS FOR FUNCTIONS
    Functions can be declared with default args, just use an `=' and fill
    in the right hand side.
    e.g.:
        int func(int a = 3, struct _a b = {2.3,4,1}, char *cp = "hello")
        {
        	....	
        }
    Functions with default args can be called with 0 or more actual args.
    They can also be called normally.
    e.g.:
        func(cp: "goodby"); // a and b will take the default values
        func(3,B,ptr);      // a, b, and cp are fully specified
		func(3);            // b and cp will take the default values
		func();             // a, b, and cp take the default values


    LABELED IDENTIFIERS FOR INITIALIZING ARRAYS AND STRUCTURES
    This extension is inspired by GCC 2.6.x .
    e.g.:
        int array[200] = {[5]= 2, [123]= 45};
        int array[20][50] = {[3][12]= 6, [18][23]= 8};
        struct {
          int x;
    	  int y;
    	  double q;
		  struct {
			int a;
			int b;
		  } bb;
		  struct {
			int a;
			int b;
		  } cc;
        } aa = {.q=4.6, .cc={.b = 12}};  // everything else set to 0


    COMPOUND EXPRESSIONS RETURN A VALUE
    Place parenthesis around braces to create a compound expression
    which consists of multiple statements and returns a value.
    This extension is inspired by GCC.
    e.g.:
	  int y = ({int i; 
                 for(i=0; i<200;++i)
                   if(i>x)
                    break;
                 i+x;	// mention variable to be returned
               });  // y = i+x


    NESTED FUNCTIONS
    Nested functions are functions placed inside functions at
    the location of automatic variables, i.e. before stmts following
    a left brace. All of the automatic variables of the enclosing
    function are within the scope of the nested function and do not
    have to be passed as arguments when the nested function is called.

    OXCC implements flavor #1 of nested functions in which the stack
    of the nested function coincides with the stack of the enclosing
    function. This is the most efficient way to deal with nested functions
    but precludes a nested function from being called recursively. The
    address of a nested function can be taken and passed to a syncronous
    callback. Asyncronous callbacks (such as might occur in an operating
    system like WINDOWS) will not work. Nested functions can call other
    nested functions which are within scope.

    Flavor #2 of nested functions requires that the nested function be
    extracted from it's surroundings and given a stack of it's own. A
    pointer to the stack frame of the enclosing function is passed invisibly
    whenever the nested function is called. Callbacks are implemented with
    thunks. This method produces a much slower nested function facility
    but is usually necessary when generating machine language. Asyncronous