/*
* $Id$
*/

Invoking the Harbour compiler:
==============================

   harbour <file[.prg]> [options]
or
   harbour [options] <file[.prg]>
or
   harbour [options] <file[.prg]> [options]


The command line options have to be separated by at least one space.
The option can start with either '/' character or '-' character.

The Harbour command line options:
=================================

/a               automatic memvar declaration"
-----------------
    This causes that all variables declared by PRIVATE or PUBLIC statements
    are automatically declared as MEMVAR variables.

/b               debug info"
-----------------
    The compiler generates all information required for debugging

/d<id>[=<val>]   #define <id>
-----------------

/es[<level>]     set exit severity
-----------------

    /es or /es0 - all warnings are ignored and exit code returned by the
        compiler (accessed by DOS ERRORLEVEL command) is equal to 0 if
        there are no errors in compiled source file
    /es1        - all warnings are ignored and exit code returned by the
        compiler is set to non-zero value
    /es2        - all warnings are treated as errors and no output file
        is created. The exit code is set to non-zero value.

/g<type>         output type generated is <type>
-----------------

    /gc              output type: C source (.c) (default)
    /gf              output type: Windows/DOS OBJ32 (.obj)
    /gh              output type: Harbour Portable Object (.hrb)
    /gj              output type: Java source (.java)
    /gp              output type: Pascal source (.pas)
    /gr              output type: Windows resource (.rc)

/i<path>         add #include file search path
-----------------

/l               suppress line number information
-----------------
    The compiler does not generate the source code line numbers in the output
    file.  The PROCLINE() function will return 0 for modules compiled using
    this option.

/m               compile module only
-----------------

/n               no implicit starting procedure
-----------------
    The compiler does not create a procedure with the same name as the compiled
    file. This causes that any declarations placed before the first PROCEDURE
    or FUNCTION statement have the file wide scope and can be accessed/used
    in all functions/procedures defined in the compiled source file. All
    executable statements placed on the beginning of the file and before the
    first PROCEDURE/FUNCTION statement are ignored.

/o<path>         object file drive and/or path
-----------------

/p               generate pre-processed output (.ppo) file
-----------------
    The compiler creates the file that contain the result of pre-processing
    of the source file.

/q               quiet
-----------------
    The compiler does not print any messages during compiling (except the
    copyright info).
    /q0     be really quiet and don't display even copyright info

/r[<lib>]        request linker to search <lib> (or none)
-----------------
    Currently not supported in Harbour.

/s               syntax check only
-----------------
    The compiler checks the syntax only. No output file is generated.

/t<path>         path for temp file creation
-----------------
    Currently not used in Harbour (the Harbour compile does not create any
    temporary files at this moment).

/u[<file>]       use command def set in <file> (or none)
-----------------
    Not supported yet.

/v               variables are assumed M->
-----------------
    All undeclared or unaliased variables are assumed MEMVAR variables
    (private or public variables). If this switch is not used then the
    scope of such variables is checked at runtime.

/w[<level>]      set warning level number (0..3, default 1)
-----------------

    /w0         - no warnings
    /w or /w1   - Clipper compatible warnings
    /w2         - some usefull warnings missed in Clipper
    /w3         - warnings generated for Harbour language extensions

/x[<prefix>]     set symbol init function name prefix (for .c only)
-----------------
    Sets the prefix added to the generated symbol init function name (in C
    output currently). This function is generated automatically for every
    PRG module compiled. This additional prefix can be used to suppress
    problems with duplicated symbols during linking an application with
    some third party libraries.

/y               trace lex & yacc activity
-----------------
    The Harbour compiler uses the FLEX and YACC utilities to parse the source
    code and to generate the required output file. This option allows to trace
    the activity of these utilities.

/z               suppress shortcutting (.and. & .or.)
-----------------

/10              restrict symbol length to 10 characters
-----------------
    All variable and function names are cut to maximum 10 characters.


Compilation in batch mode.
==========================

 @<file>         compile list of modules in <file>
-----------------
    Not supported yet.



Known incompatibilities between harbour and clipper compilers
=============================================================

NOTE: 
  If you want 100% compatible compiler and runtime libraries then
you have to define HARBOUR_STRICT_CLIPPER_COMPATIBILITY option. This
option should be defined in include/hbsetup.h file (in fact this
option is placed into comment by default - you need remove /* */
characters only). This change have to be done before invoking
the make utility.


Handling of undeclared variables 
--------------------------------
  When a value is assigned to an undeclared variable and '-v' command
line option is not used then the Clipper compiler assumes that the variable 
is a PRIVATE or a PUBLIC variable and generates POPM (pop memvar) opcode.
  When a value of undeclared variable is accessed and '-v' command line
option is not used the Clipper compiler generates PUSHV (push variable)
opcode that determines the type of variable at runtime. If the field with
requested name exists in a current workarea then its value is used. If there
is no field then a PRIVATE or a PUBLIC variable is used (if exists).

  The Harbour compiler generates an opcode to determine the type of variable 
at runtime (POPVARIABLE or PUSHVARIABLE) in both cases (assignment and access). 

The difference can be checked by the following code:

PROCEDURE MAIN()
PRIVATE myname

  DBCREATE( "TEST", { { "MYNAME", "C", 10, 0} } )
  USE test NEW
  SELECT test
  APPEND BLANK

  FIELD->myname  := "FIELD"
  MEMVAR->myname := "MEMVAR"

  myname := myname + " assigned"

  ? FIELD->myname   //In Clipper: "FIELD",  In Harbour: "FIELD assigned"
  ? MEMVAR->myname  //In Clipper: "MEMVAR assigned", In Harbour: "MEMVAR"

  USE

RETURN


Passing an undeclared variable by the reference
-----------------------------------------------
  The Clipper compiler uses the special opcode PUSHP to pass a reference
to an undeclared variable ( '@' operator ). The type of passed variable
is checked at runtime (field or memvar). However the field variables
cannot be passed by the reference. It causes that Clipper checks the
memvar variable only and doesn't look for a field. This is the reason
why the Harbour compiler uses the usual PUSHMEMVARREF opcode in such
cases. Notice that the runtime behavior is the same in Clipper and
in Harbour - the generated opcodes are different only.

