/*
 * $Id$
 */

/*  $DOC$
 *  $TEMPLATE$
 *     Document
 *  $NAME$
 *      Compiler Options
 *  $CATEGORY$
 *      Document
 *  $SUBCATEGORY$
 *      Compiler
 *  $ONELINER$
 *      Compiler Options
 *  $DESCRIPTION$
 *
 *      <b>Invoking the Harbour compiler:  </b> </par>
 *      ==============================   </par>
 *
 *         harbour <file[.prg]> [options]   </par>
 *      or                                  </par>
 *         harbour [options] <file[.prg]>   </par>
 *      or   </par>
 *         harbour [options] <file[.prg]> [options]   </par>
 *
 *      The command line options have to be separated by at least one space.
 *      The option can start with either '/' character or '-' character.
 *
 *      <b>The Harbour command line options:  </b> </par>
 *      =================================   </par>
 *
 *      /a               automatic memvar declaration   </par>
 *      =================   </par>
 *
 *          This causes all variables declared by PARAMETER, PRIVATE or PUBLIC
 *          statements to be automatically declared as MEMVAR variables.
 *
 *      /b               debug info   </par>
 *      =================   </par>
 *
 *          The compiler generates all information required for debugging
 *
 *      /d<id>[=<val>]   #define <id>   </par>
 *      =================   </par>
 *
 *      /es[<level>]     set exit severity   </par>
 *      =================   </par>
 *
 *          /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        - any warnings generate a non-zero exit code, but
 *                        output is still created.
 *
 *          /es2        - all warnings are treated as errors and no output
 *                        file is created. The exit code is set to a non-zero
 *                        value.

 *      /g<type>         output type generated is <type> </par>
 *      =================   </par>
 *
 *          /gc[<type>]  output type: C source (.c) (default)
 *                          <type>: 0=compact 1=normal 2=verbose (default)
 *                                  3=generate real C code instead of PCODE
 *                                    array called by a C wrapper.
 *
 *          /go          output type: Platform dependant object module
 *
 *          /gh          output type: Harbour Portable Object (.hrb)
 *

 *      /i<path>         add #include file search path   </par>
 *      =================   </par>
 *
 *      /k<mode>         enable <mode> compatibility mode  </par>
 *      =================                                  </par>
 *
 *          /kc          clear all flags (strict CA-Cl*pper compatibility)
 *
 *          /kh          Harbour extensions (default)
 *
 *          /ki          HB_INLINE support enabled (default)
 *
 *          /kr          use runtime settings for the macro compiler
 *
 *          /ks          enable support for strings as array of bytes (default)
 *
 *          /kx          other Xbase++ dialects extensions (default)
 *
 *          /kJ          disable optimalization of jump and noop pcodes
 *
 *          /k?          invoke help information
 *
 *      /l               suppress line number information      </par>
 *      =================   </par>
 *
 *          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 current module only   </par>
 *      =================   </par>
 *
 *      /n               no implicit starting procedure   </par>
 *      =================   </par>
 *
 *          The compiler does not create a procedure with the same name as
 *          the compiled file. This means that any declarations placed
 *          before the first PROCEDURE or FUNCTION statement have file-
 *          wide scope and can be accessed/used in all functions/procedures
 *          defined in the compiled source file. All executable statements
 *          placed at the beginning of the file and before the first
 *          PROCEDURE/FUNCTION statement are ignored.
 *
 *      /o<path>         output file drive and/or path   </par>
 *      =================   </par>
 *
 *      /p               generate pre-processed output (.ppo) file   </par>
 *      =================   </par>
 *
 *          The compiler only creates the file that contains the result of
 *          pre-processing the source file.
 *
 *      /q               quiet   </par>
 *      =================   </par>
 *
 *          The compiler does not print any messages during compiling
 *          (except the copyright info).
 *
 *          /q0     be really quiet and don't display even the copyright info
 *
 *      /r[<lib>]        request linker to search <lib> (or none)   </par>
 *      =================   </par>
 *
 *          Currently not supported in Harbour.
 *
 *      /r=<max>         sets maximum number of preprocessor iterations </par>
 *      =================   </par>
 *
 *          This set the maximum number of preprocessor iterations
 *          during processing the source code. If this switch is not
 *          used then the preprocessor stops after 1024 iterations.
 *          This value is used to stop processing of infinite loops,
 *          for example:
 *          #command ( => (,7
 *
 *      /s               syntax check only   </par>
 *      =================   </par>
 *
 *          The compiler checks the syntax only. No output file is generated.
 *
 *      /t<path>         path for temp file creation   </par>
 *      =================   </par>
 *
 *          Currently not used in Harbour (the Harbour compiler does not
 *          create any temporary files).
 *
 *      /u[<file>]       use command definition set in <file> (or none)   </par>
 *      =================   </par>
 *
 *      /v               variables are assumed M->   </par>
 *      =================   </par>
 *
 *          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..4, default 1)   </par>
 *      =================   </par>
 *
 *          /w0         - no warnings
 *
 *          /w or /w1   - CA-Cl*pper compatible warnings
 *
 *          /w2         - some useful warnings missed in CA-Cl*pper
 *
 *          /w3         - warnings generated for Harbour language extensions
 *                        and also enables strong type checking but only
 *                        warns against declared types, or types which may be
 *                        calculated at compile time
 *
 *          /w4         - Enables warning about suspicious operations, which
 *                        means if you mix undeclared types, or types which
 *                        can not be calculated at compile time,together with
 *                        declared types, a warning will be  generated.
 *
 *      /x[<prefix>]     set symbol init function name prefix (for .c only)   </par>
 *      =================   </par>
 *
 *          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   </par>
 *      =================   </par>
 *
 *          The Harbour compiler uses the FLEX and YACC utilities to parse
 *          the source code and to generate the required output file. This
 *          option traces the activity of these utilities.
 *
 *      /z               suppress logical shortcutting (.and. & .or.)   </par>
 *      =================   </par>
 *
 *      Compilation in batch mode.   </par>
 *      ==========================   </par>
 *
 *       @<file>         compile list of modules in <file>   </par>
 *      =================        </par>
 *
 *          Not supported yet.
 *
 *      <b>Known incompatibilities between Harbour and CA-Cl*pper compilers  </b> </par>
 *      =============================================================   </par>
 *
 *      NOTE:   </par>
 *
 *      If you want a 100% compatible runtime libraries then
 *      you have to define HARBOUR_STRICT_CLIPPER_COMPATIBILITY. This
 *      option should be defined in the file include/hbsetup.h (in fact this
 *      option is placed in a comment by default - you need to remove the
 *      /* */ characters only). This change has to be done before invoking
 *      the make utility.
 *
 *
 *      <b>Handling of undeclared variables  </b> </par>
 *      ================================   </par>
 *
 *      When a value is assigned to an undeclared variable and the '-v'
 *      command line option is not used, then the CA-Cl*pper compiler assumes
 *      that the variable is a PRIVATE or a PUBLIC variable and generates
 *      POPM (pop memvar) opcode.
 *
 *      When the value of an undeclared variable is accessed and the '-v'
 *      command line option is not used, the CA-Cl*pper compiler generates PUSHV
 *      (push variable) opcode that determines the type of variable at runtime.
 *      If a field with the requested name exists in the 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:
 *
 *      <fixed>
 *      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"
 *
 *         // In CA-Cl*pper: "FIELD",  In Harbour: "FIELD assigned"
 *         ? FIELD->myname
 *
 *         // In CA-Cl*pper: "MEMVAR assigned", In Harbour: "MEMVAR"
 *         ? MEMVAR->myname
 *
 *         USE
 *
 *         RETURN
 *      </fixed>
 *
 *      <b>Passing an undeclared variable by the reference </b>  </par>
 *      ===============================================   </par>
 *
 *      The CA-Cl*pper 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,
 *      field variables cannot be passed by reference. This means that
 *      CA-Cl*pper 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 CA-Cl*pper and in Harbour - only the generated opcodes
 *      are different.
 *
 *
 *      Handling of object messages   </par>
 *      ===========================   </par>
 *
 *        The HARBOUR_STRICT_CLIPPER_COMPATIBILITY setting determines
 *      the way chained send messages are handled.
 *
 *      For example, the following code:
 *
 *      a:b( COUNT() ):c += 1
 *
 *      will be handled as:
 *
 *      a:b( COUNT() ):c := a:b( COUNT() ):c + 1
 *
 *      in strict CA-Cl*pper compatibility mode and
 *
 *      temp := a:b( COUNT() ), temp:c += 1
 *
 *      in non-strict mode.
 *
 *      In practice, CA-Cl*pper will call the COUNT() function two times:
 *      the first time before addition and the second one after addition.
 *      In Harbour, COUNT() will be called only once, before addition.
 *
 *      The Harbour (non-strict) method is:   </par>
 *      1) faster   </par>
 *      2) it guarantees that the same instance variable of the same object
 *      will be changed
 *
 *      (See also: src/compiler/expropt.c)
 *
 *      <b>Initialization of static variables      </b></par>
 *      ==================================      </par>
 *
 *      There is a difference in the initialization of static
 *      variables that are initialized with a codeblock that refers to
 *      a local variable. For example:

 *      <fixed>
 *      PROCEDURE TEST()
 *      LOCAL MyLocalVar
 *      STATIC MyStaticVar := {|| MyLocalVar }
 *
 *        MyLocalVar :=0
 *        ? EVAL( MyStaticVar )
 *
 *      RETURN
 *      </fixed>

 *      The above code compiles fine in CA-Cl*pper, but it generates a
 *      runtime error Error/BASE 1132 Bound error: array access
 *      Called form (b)STATICS$(0)
 *
 *      In Harbour this code generates a compile time error:
 *      Error E0009 Illegal variable (b) initializer: 'MyLocalVar'
 *
 *      Both CA-Cl*pper and Harbour are handling all local variables used in a
 *      codeblock in a special way: they are detached from the local stack
 *      of function/procedure where they are declared. This allows access to
 *      these variables after the exit from a function/procedure. However,
 *      all static variables are initialized in a separate procedure
 *      ('STATICS$' in CA-Cl*pper and '(_INITSTATICS)' in Harbour) before the
 *      main procedure and before all INIT procedures. The local variables
 *      don't exist on the eval stack when static variables are initialized,
 *      so they cannot be detached.
 *
 *  $END$
 */