diff --git a/harbour/ChangeLog b/harbour/ChangeLog index 01915601a3..89c7b7e517 100644 --- a/harbour/ChangeLog +++ b/harbour/ChangeLog @@ -1,3 +1,19 @@ +20000209-20:00 GMT-3 Luiz Rafael Culik + *utils/hbdoc/hbdoc.prg + *Separated in several files + +utils/hbdoc/genos2.prg + +utils/hbdoc/gentrf.prg + +utils/hbdoc/genng.prg + +utils/hbdoc/genhtm.prg + +utils/hbdoc/genrtf.prg + +utils/hbdoc/genhpc.prg + +utils/hbdoc/genasc.prg + *Contains the Procedures to create the output files + *utils/hbdoc/Makefile + +Added the new hbdoc modules + *makefile.b32 + *Update for hbdoc changes + 20000209-13:30 GMT+1 Antonio Linares * source/debug/debugger.prg + Added INKEY_ALL second parameter to Inkey() call. diff --git a/harbour/doc/compiler.txt b/harbour/doc/compiler.txt index c6f0f78ba8..01354611cc 100644 --- a/harbour/doc/compiler.txt +++ b/harbour/doc/compiler.txt @@ -1,273 +1,283 @@ /* * $Id$ */ - -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 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[=] #define ------------------ - -/es[] 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 output type generated is ------------------ - - /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 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 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[] request linker to search (or none) ------------------ - Currently not supported in Harbour. - -/s syntax check only ------------------ - The compiler checks the syntax only. No output file is generated. - -/t path for temp file creation ------------------ - Currently not used in Harbour (the Harbour compile does not create any - temporary files at this moment). - -/u[] use command def set in (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[] 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[] 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. -========================== - - @ compile list of modules in ------------------ - 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. - - -Handling of object messages ---------------------------- - The HARBOUR_STRICT_CLIPPER_COMPATIBILITY setting determines -the way the 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 in Clipper it will call COUNT() function two times: the -first time before addition and the second one after addition - in Harbour, -COUNT() function 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: source/compiler/expropt.c) - -Initialization of static variables ----------------------------------- - -There is a difference in handling of initialization of static variables that -are initialized with a codeblock that refers to a local variarble. -For example: - -PROCEDURE TEST() -LOCAL MyLocalVar -STATIC MyStaticVar := {|| MyLocalVar} - - MyLocalVar :=0 - ? EVAL( MyStaticVar ) - -RETURN - -The above code compiles fine in Clipper however 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 handing 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 to access 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 then -they cannot be detached. - +/* $DOC$ + * $FUNCNAME$ + * Compiler Options + * $CATEGORY$ + * Document + * $ONELINER$ + * Compiler Options + * $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 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[=] #define + * ----------------- + * + * /es[] 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 output type generated is + * ----------------- + * + * /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 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 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[] request linker to search (or none) + * ----------------- + * Currently not supported in Harbour. + * + * /s syntax check only + * ----------------- + * The compiler checks the syntax only. No output file is generated. + * + * /t path for temp file creation + * ----------------- + * Currently not used in Harbour (the Harbour compile does not create any + * temporary files at this moment). + * + * /u[] use command def set in (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[] 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[] 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. + * ========================== + * + * @ compile list of modules in + * ----------------- + * 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. + * + * + * Handling of object messages + * --------------------------- + * The HARBOUR_STRICT_CLIPPER_COMPATIBILITY setting determines + * the way the 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 in Clipper it will call COUNT() function two times: the + * first time before addition and the second one after addition - in Harbour, + * COUNT() function 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: source/compiler/expropt.c) + * + * Initialization of static variables + * ---------------------------------- + * + * There is a difference in handling of initialization of static variables that + * are initialized with a codeblock that refers to a local variarble. + * For example: + * + * PROCEDURE TEST() + * LOCAL MyLocalVar + * STATIC MyStaticVar := {|| MyLocalVar} + * + * MyLocalVar :=0 + * ? EVAL( MyStaticVar ) + * + * RETURN + * + * The above code compiles fine in Clipper however 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 handing 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 to access 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 then + * they cannot be detached. + * + * $END$ + */ diff --git a/harbour/makefile.b32 b/harbour/makefile.b32 index a29d677e4e..5a694643cf 100644 --- a/harbour/makefile.b32 +++ b/harbour/makefile.b32 @@ -243,7 +243,14 @@ REGRESS_EXE_OBJS = $(REGRESS_DIR)\rt_main.obj \ $(REGRESS_DIR)\rt_misc.obj HBDOC_EXE = $(HBDOC_DIR)\hbdoc.exe -HBDOC_EXE_OBJS = $(HBDOC_DIR)\hbdoc.obj +HBDOC_EXE_OBJS = $(HBDOC_DIR)\hbdoc.obj \ + $(HBDOC_DIR)\genos2.obj \ + $(HBDOC_DIR)\gentrf.obj \ + $(HBDOC_DIR)\genng.obj \ + $(HBDOC_DIR)\genhtm.obj \ + $(HBDOC_DIR)\genrtf.obj \ + $(HBDOC_DIR)\genhpc.obj \ + $(HBDOC_DIR)\genasc.obj PROJECT: $(COMMON_LIB) \ $(PP_LIB) \ @@ -1312,12 +1319,20 @@ $(REGRESS_DIR)\rt_misc.obj : $(REGRESS_DIR)\rt_misc.c # # hbdoc.exe # + $(HBDOC_EXE) : $(HBDOC_EXE_OBJS) echo $(BCC_OPT) > temp.bld echo -e$(HBDOC_DIR)\hbdoc.exe >> temp.bld echo -I$(INCLUDE_DIR) >> temp.bld echo $(HBDOC_DIR)\hbdoc.obj >> temp.bld + echo $(HBDOC_DIR)\genos2.obj >> temp.bld + echo $(HBDOC_DIR)\gentrf.obj >> temp.bld + echo $(HBDOC_DIR)\genng.obj >> temp.bld + echo $(HBDOC_DIR)\genhtm.obj >> temp.bld + echo $(HBDOC_DIR)\genrtf.obj >> temp.bld + echo $(HBDOC_DIR)\genhpc.obj >> temp.bld + echo $(HBDOC_DIR)\genasc.obj >> temp.bld echo $(HARBOUR_LIB) >> temp.bld echo $(PP_LIB) >> temp.bld echo $(COMMON_LIB) >> temp.bld @@ -1333,4 +1348,49 @@ $(HBDOC_DIR)\hbdoc.c : $(HBDOC_DIR)\hbdoc.prg $(HARBOUR_EXE) $** -i$(INCLUDE_DIR) -n -q -o$@ $(HBDOC_DIR)\hbdoc.obj : $(HBDOC_DIR)\hbdoc.c - bcc32 $(BCC_OPT) -c -I$(INCLUDE_DIR) -o$@ $** \ No newline at end of file + bcc32 $(BCC_OPT) -c -I$(INCLUDE_DIR) -o$@ $** + +$(HBDOC_DIR)\genos2.obj : $(HBDOC_DIR)\genos2.c + bcc32 $(BCC_OPT) -c -I$(INCLUDE_DIR) -o$@ $** + +$(HBDOC_DIR)\genos2.c : $(HBDOC_DIR)\genos2.prg + $(HARBOUR_EXE) $** -i$(INCLUDE_DIR) -n -q -o$@ + +$(HBDOC_DIR)\genng.c : $(HBDOC_DIR)\genng.prg + $(HARBOUR_EXE) $** -i$(INCLUDE_DIR) -n -q -o$@ + +$(HBDOC_DIR)\genng.obj : $(HBDOC_DIR)\genng.c + bcc32 $(BCC_OPT) -c -I$(INCLUDE_DIR) -o$@ $** + +$(HBDOC_DIR)\genhtm.c : $(HBDOC_DIR)\genhtm.prg + $(HARBOUR_EXE) $** -i$(INCLUDE_DIR) -n -q -o$@ + +$(HBDOC_DIR)\genhtm.obj : $(HBDOC_DIR)\genhtm.c + bcc32 $(BCC_OPT) -c -I$(INCLUDE_DIR) -o$@ $** + +$(HBDOC_DIR)\gentrf.c : $(HBDOC_DIR)\gentrf.prg + $(HARBOUR_EXE) $** -i$(INCLUDE_DIR) -n -q -o$@ + +$(HBDOC_DIR)\gentrf.obj : $(HBDOC_DIR)\gentrf.c + bcc32 $(BCC_OPT) -c -I$(INCLUDE_DIR) -o$@ $** + +$(HBDOC_DIR)\genasc.c : $(HBDOC_DIR)\genasc.prg + $(HARBOUR_EXE) $** -i$(INCLUDE_DIR) -n -q -o$@ + +$(HBDOC_DIR)\genasc.obj : $(HBDOC_DIR)\genasc.c + bcc32 $(BCC_OPT) -c -I$(INCLUDE_DIR) -o$@ $** + +$(HBDOC_DIR)\genhpc.c : $(HBDOC_DIR)\genhpc.prg + $(HARBOUR_EXE) $** -i$(INCLUDE_DIR) -n -q -o$@ + +$(HBDOC_DIR)\genhpc.obj : $(HBDOC_DIR)\genhpc.c + bcc32 $(BCC_OPT) -c -I$(INCLUDE_DIR) -o$@ $** + +$(HBDOC_DIR)\genrtf.c : $(HBDOC_DIR)\genrtf.prg + $(HARBOUR_EXE) $** -i$(INCLUDE_DIR) -n -q -o$@ + +$(HBDOC_DIR)\genrtf.obj : $(HBDOC_DIR)\genrtf.c + bcc32 $(BCC_OPT) -c -I$(INCLUDE_DIR) -o$@ $** + + +