harbour-core/doc/en/compiler.txt

/* $DOC$
   $TEMPLATE$
      Document
   $NAME$
      Compiler Options
   $CATEGORY$
      Document
   $SUBCATEGORY$
      Compiler
   $DESCRIPTION$
      <b>Invoking the Harbour compiler:</b>
      ==============================

      ```
      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.

      <b>The Harbour command-line options:</b>
      =================================

      `-a`               automatic memvar declaration

          This causes all variables declared by PARAMETER, PRIVATE or PUBLIC
          statements to be automatically declared as MEMVAR variables.

      =================
      `-b`               debug info

          The compiler generates all information required for debugging

      =================
      `-build`           display detailed version info

      =================
      `-credits`         display credits

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

      =================
      `-es[<level>]`     set exit severity

          `-es` or `-es0` - all warnings are ignored and exit code returned by
                            the compiler 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.

      =================
      `-fn[:[l|u]|-]`    set file name casing (`l`=lower `u`=upper)

      =================
      `-fd[:[l|u]|-]`    set directory casing (`l`=lower `u`=upper)

      =================
      `-fp[:<char>]`     set path separator

      =================
      `-fs[-]`           turn file name space trimming on or off (default)

      =================
      `-g<type>`         output type generated is <type>

          `-gc[<type>]`  output type: C source `.c` (default)
                          <type>: `0`=compact (default) `1`=normal `2`=verbose
                                  `3`=generate real C code

          `-gh`          output type: Harbour Portable Object `.hrb`

          `-gd[.<destext>]`  generate dependencies list into `.d` file

          `-ge[<mode>]`      error output <mode>: `0`=Clipper (default)
                                                  `1`=IDE friendly

      =================
      `-i<path>`         #include file search path

      =================
      `-i[-|+]`          disable/enable support for INCLUDE envvar

      =================
      `-j[<file>]`     generate i18n gettext file `.pot`

      =================
      `-k<mode>`       compilation mode (type `-k?` for more data)

          `-kc`        clear all flags (strict Clipper mode)

          `-kh`        Harbour mode (default)

          `-ko`        allow operator optimizations

          `-ki`        enable support for HB_INLINE (default)

          `-kr`        runtime settings enabled

          `-ks`        allow indexed assignment on all types

          `-kx`        extended Xbase++ mode (default)

          `-ku`        strings in user encoding

          `-kd`        accept macros with declared symbols

          `-km`        turn off macro-text substitution

          `-kj`        turn off jump optimization in pcode

          `-k?`        this info

      =================
      `-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[<type>]`       no implicit starting procedure

                         <type>: `0`=no implicit starting procedure
                                 `1`=no starting procedure at all
                                 `2`=add starting procedure if necessary

          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>`         object file drive and/or path

      =================
      `-p`               generate pre-processed output `.ppo` file

          The compiler only creates the file that contains the result of
          pre-processing the source file.

      =================
      `-p+`              generate pre-processor trace `.ppt` file

      =================
      `-q`               quiet

          The compiler does not print any messages during compiling
          (except the copyright info).

          `-q0`     quiet and don't display program header

          `-q2`     disable all output messages

          `-ql`     suppress line number information

      =================
      `-r[<lib>]`        request linker to search <lib> (or none)

          Currently not supported in Harbour.

      =================
      `-r=<max>`         sets maximum number of preprocessor iterations

          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[m]`            syntax check only [minimal for dependencies list]

          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 compiler does not
          create any temporary files).

      =================
      `-u[<file>]`       use command def set in <file> (or none)

      =================
      `-u+<file>`        add command def set from <file>

      =================
      `-undef:<id>`      `#undef <id>`

      =================
      `-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` - 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

      =================
      `-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.

      =================
      `-z`               suppress shortcutting (`.AND.` & `.OR.`)

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

       `@file`         compile list of modules in <file>

          Not supported yet.

      <b>Known incompatibilities between Harbour and CA-Cl*pper compilers</b>
      =============================================================

      Note:

      If you want a 100% compatible runtime libraries then you have
      to define HB_CLP_STRICT, using `HB_USER_CFLAGS=-DHB_CLP_STRICT`,
      then rebuild.

      <b>Passing an undeclared variable by the reference</b>
      ===============================================

      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
      ===========================

      The HB_CLP_STRICT 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:

      1) faster

      2) it guarantees that the same instance variable of the same object
      will be changed

      (See also: include/hbexpra.c, include/hbexprb.c)

      <b>Initialization of static variables</b>
      ==================================

      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>
      LOCAL MyLocalVar
      STATIC s_MyStaticVar := {|| MyLocalVar }

      MyLocalVar := 0
      ? Eval( s_MyStaticVar )
      </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$
 */