/*
 * $Id: compiler.txt,v 1.14 2003/11/10 11:28:18 rglab Exp $
 */

/*  $DOC$
 *  $FUNCNAME$
 *      Compiler Options
 *  $CATEGORY$
 *      Document
 *  $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)
 *
 *          /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 Clipper 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.   
 *
 *      /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   - Clipper compatible warnings
 *
 *          /w2         - some useful warnings missed in Clipper
 *
 *          /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 clipper 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 Clipper 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 Clipper 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 Clipper: "FIELD",  In Harbour: "FIELD assigned"
 *        ? FIELD->myname
 *
 *        // In Clipper: "MEMVAR assigned", In Harbour: "MEMVAR"
 *        ? MEMVAR->myname
 *
 *        USE
 *
 *      RETURN
 *     </fixed>
 *         
 *      <b>Passing an undeclared variable by the reference </b>  </par>
 *      ===============================================   </par>
 *
 *      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,
 *      field variables cannot be passed by reference. This means 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 - 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 Clipper compatibility mode and   
 *
 *      temp := a:b( COUNT() ), temp:c += 1   
 *
 *      in non-strict mode.   
 *
 *      In practice, Clipper 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: source/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 Clipper, 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 Clipper 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 Clipper 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$
 */
