/* $DOC$ $TEMPLATE$ Document $NAME$ Compiler Options $CATEGORY$ Document $SUBCATEGORY$ Compiler $DESCRIPTION$ Invoking the Harbour compiler: ============================== ``` harbour [options] ``` or ``` harbour [options] ``` or ``` harbour [options] [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 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[=]` `#define ` ================= `-es[]` 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[:]` set path separator ================= `-fs[-]` turn file name space trimming on or off (default) ================= `-g` output type generated is `-gc[]` output type: C source `.c` (default) : `0`=compact (default) `1`=normal `2`=verbose `3`=generate real C code `-gh` output type: Harbour Portable Object `.hrb` `-gd[.]` generate dependencies list into `.d` file `-ge[]` error output : `0`=Clipper (default) `1`=IDE friendly ================= `-i` #include file search path ================= `-i[-|+]` disable/enable support for INCLUDE envvar ================= `-j[]` generate i18n gettext file `.pot` ================= `-k` 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[]` no implicit starting procedure : `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` 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[]` request linker to search (or none) Currently not supported in Harbour. ================= `-r=` 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 for temp file creation Currently not used in Harbour (the Harbour compiler does not create any temporary files). ================= `-u[]` use command def set in (or none) ================= `-u+` add command def set from ================= `-undef:` `#undef ` ================= `-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[]` 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[]` 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 Not supported yet. Known incompatibilities between Harbour and CA-Cl*pper compilers ============================================================= 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. Passing an undeclared variable by the reference =============================================== 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) Initialization of static variables ================================== There is a difference in the initialization of static variables that are initialized with a codeblock that refers to a local variable. For example: LOCAL MyLocalVar STATIC s_MyStaticVar := {|| MyLocalVar } MyLocalVar := 0 ? Eval( s_MyStaticVar ) 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$ */