diff --git a/harbour/ChangeLog b/harbour/ChangeLog index c354a0dda3..96bc365bba 100644 --- a/harbour/ChangeLog +++ b/harbour/ChangeLog @@ -1,3 +1,11 @@ +20000213-11:23 GMT+2 Chen Kedem + * doc/compiler.txt + * doc/readme.txt + * doc/statics.txt + * doc/whatsnew.txt + * Formating for 80 column (actually 76 like the NG standard) + + CVS ID added + 20000213-04:02 GMT+1 Victor Szakats * source/compiler/cmdcheck.c ! Fixed broken handling of the /x switch without parameter. @@ -80,7 +88,7 @@ * source/rtl/Makefile - readvar.prg removed. * doc/harbext.txt - + CVD ID added + + CVS ID added !! Please remember to add this to every file CVS-d !! * tests/bld_b16.bat tests/bld_b32.bat diff --git a/harbour/doc/compiler.txt b/harbour/doc/compiler.txt index 01354611cc..57ce7c865c 100644 --- a/harbour/doc/compiler.txt +++ b/harbour/doc/compiler.txt @@ -1,6 +1,7 @@ /* -* $Id$ -*/ + * $Id$ + */ + /* $DOC$ * $FUNCNAME$ * Compiler Options @@ -9,156 +10,160 @@ * $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. - * + * 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. - * + * + * /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) - * + * + * /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. - * + * 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. - * + * 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. - * + * 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). + * 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). - * + * 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. - * + * 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. - * + * 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. - * + * 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 @@ -166,118 +171,127 @@ * 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). - * + * 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" - * + * + * // In Clipper: "FIELD", In Harbour: "FIELD assigned" + * ? FIELD->myname + * + * // In Clipper: "MEMVAR assigned", In Harbour: "MEMVAR" + * ? MEMVAR->myname + * * 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. - * - * + * 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. - * + * + * 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 - * + * 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: - * + * + * 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} - * + * 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 + * + * 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. - * + * 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/doc/readme.txt b/harbour/doc/readme.txt index 135961dcd2..28a6b5530e 100644 --- a/harbour/doc/readme.txt +++ b/harbour/doc/readme.txt @@ -1,5 +1,6 @@ - - +/* + * $Id: + */ The Harbour project @@ -35,7 +36,7 @@ What this distribution contains =============================== This distribution is a Source code only distribution. It does not contain -any executable files. Executable versions of Harbour are available from +any executable files. Executable versions of Harbour are available from the web site. Executable versions of Harbour DO NOT create runable programs. Harbour at the moment produces C output code, which must be compiled with the Harbour Virtual Machine and the support libraries @@ -63,7 +64,6 @@ Installation What copyright information do we have - --- LICENCE --- Information about the License for usage of Harbour is available in the @@ -71,13 +71,23 @@ file LICENCE.TXT (when we have a license) --- DISCLAIMER --- -Participants of The Harbour Project assume no responsibility for errors or omissions in these materials. +Participants of The Harbour Project assume no responsibility for errors or +omissions in these materials. -THESE MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. +THESE MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. -Participants of The Harbour Project further do not warrant the accuracy or completeness of the code, information, text, output or any other items contained within these materials. Participants of The Harbour Project shall not be liable for any special, direct, indirect, incidental, or consequential damages, including without limitation, lost revenues or lost profits, which may result from the use or mis-use of these materials. +Participants of The Harbour Project further do not warrant the accuracy or +completeness of the code, information, text, output or any other items +contained within these materials. Participants of The Harbour Project shall +not be liable for any special, direct, indirect, incidental, or +consequential damages, including without limitation, lost revenues or lost +profits, which may result from the use or mis-use of these materials. -The information in The Harbour Project is subject to change without notice and does not represent any future commitment by the participants of The Harbour Project. +The information in The Harbour Project is subject to change without notice +and does not represent any future commitment by the participants of The +Harbour Project. The Harbour Project diff --git a/harbour/doc/statics.txt b/harbour/doc/statics.txt index f67fef068d..9e646dc67c 100644 --- a/harbour/doc/statics.txt +++ b/harbour/doc/statics.txt @@ -1,12 +1,29 @@ -I just started implementing Classes and objects creation when I realized Harbour is not managing statics variables yet (Harbour recognizes them but does not generate the proper pcode for them). +/* + * $Id: + */ -So I would like to make an introduction to statics variables management as it is a sophisticated system that Harbour is going to implement. + I just started implementing Classes and objects creation when I realized +Harbour is not managing statics variables yet (Harbour recognizes them but +does not generate the proper pcode for them). -It is something publically known that Clipper statics variables are located at the bottom of the data segment. This has caused all kind of troubles. This is why when I designed Five I did it in a way that could not cause any trouble in the future. + So I would like to make an introduction to statics variables management as +it is a sophisticated system that Harbour is going to implement. -In Harbour all statics variables (and I mean on all PRGs) are stored in just one Harbour array (a Clipper language array), this guaranties that we may have as many statics variables as desired without limits (just limited by the available memory). This aStatics array is not visible from the application (PRG level). + It is something publically known that Clipper statics variables are +located at the bottom of the data segment. This has caused all kind of +troubles. This is why when I designed Five I did it in a way that could not +cause any trouble in the future. -Basically what happens when a function is called and that function uses static variables, is that the stack sets a pointer to that array section where our statics are, so from that moment on, accessing a static1, static2, ... is accessing some elements on that array: + In Harbour all statics variables (and I mean on all PRGs) are stored in +just one Harbour array (a Clipper language array), this guaranties that we +may have as many statics variables as desired without limits (just limited +by the available memory). This aStatics array is not visible from the +application (PRG level). + + Basically what happens when a function is called and that function uses +static variables, is that the stack sets a pointer to that array section +where our statics are, so from that moment on, accessing a static1, static2, +... is accessing some elements on that array: static1 = statics[ statics_base_for_this_function + 1 ] @@ -14,17 +31,23 @@ Basically what happens when a function is called and that function uses static v staticn = statics[ statics_base_for_this_function + n ] -In order to implement this we just use two new pcode opcodes: _STATICS, _SFRAME + In order to implement this we just use two new pcode opcodes: _STATICS, +_SFRAME. _STATICS makes the global statics array grow enough to hold our new +defined statics: -_STATICS makes the global statics array grow enough to hold our new defined statics: - - _STATICS --> ASize( aStatics, Len( aStatics ) + ) + _STATICS --> ASize( aStatics, Len( aStatics ) + ) _SFRAME --> tell the stack from what location into aStatics are ours. -_STATICS is just called once from an entire PRG from an init function named _INITSTATICS (STATICS$ and SINIT in Clipper). That function stores on a tricky place (its own function pointer in the symbol table!) our statics base, and later on _SFRAME simply takes it from there and set it in the stack. That _INITSTATICS function will perform whatever initialization our global statics may have defined in that PRG). + _STATICS is just called once from an entire PRG from an init function +named _INITSTATICS (STATICS$ and SINIT in Clipper). That function stores on +a tricky place (its own function pointer in the symbol table!) our statics +base, and later on _SFRAME simply takes it from there and set it in the +stack. That _INITSTATICS function will perform whatever initialization our +global statics may have defined in that PRG). -You are going to see the code for all these. I just wanted to provide a clear idea about how Harbour does its magic :-) + You are going to see the code for all these. I just wanted to provide a +clear idea about how Harbour does its magic :-) -Antonio +Antonio diff --git a/harbour/doc/whatsnew.txt b/harbour/doc/whatsnew.txt index 91366bbe22..4deb278b01 100644 --- a/harbour/doc/whatsnew.txt +++ b/harbour/doc/whatsnew.txt @@ -1,14 +1,25 @@ +/* + * $Id: + */ + +---------------------------------------------------------------------- + Build 0.31a 2000-02-02 -- Bugs fixed. + +- Bugs fixed + +---------------------------------------------------------------------- Build #31 2000-01-27 + - Added macro support - Many changes, fixes, and enhancements to compiler internals - Many changes, fixes, and enhancements to RDD system - Many changes, fixes, and enhancements to the GT API system - Improved SETCURSOR() and SET( _SET_CURSOR ) - Added FIELDBLOCK() and FIELDWBLOCK() -- The Harbour '-w' command line option can set the maximal level of reported warnings. The following levels are supported currently: +- The Harbour '-w' command line option can set the maximal level of reported + warnings. The following levels are supported currently: '-w0' - no warnings '-w' or '-w1' - Clipper compatible warnings '-w2' - some useful warnings missed in Clipper @@ -17,13 +28,15 @@ Build #31 2000-01-27 - The 'runner' program is now named 'hbrun'. - Some include files now have an 'hb' prefix in the name. - db_brows significantly enhanced. -- Regression testing enhanced and expanded, replacing several standalone test modules. Now in tests/regress directory. +- Regression testing enhanced and expanded, replacing several standalone + test modules. Now in tests/regress directory. - Added FSETDEVMOD() - Added READINSERT() - Added MEMOLINE() - Added undocumented DISPOUTAT() - Added DEFPATH() and __DEFPATH() -- Enhanced VERSION() to optionally include the compiler version used to create Harbour +- Enhanced VERSION() to optionally include the compiler version used to + create Harbour - Enhanced OS() to include more Windows version details - Added __INPUT(), __WAIT(), and SETTYPEAHEAD() - Added several undocumented __BOX*() functions @@ -52,7 +65,8 @@ Build #31 2000-01-27 ISAFFIRM(), ISNEGATIVE(), NATIONMSG(), _NATSORTVER(), _NATMSGVER() - Added Harbour compiler tracing (i.e., debug output) - Many changes, fixes, and enhancements to documentation -- Program added to extract documentation from source code and create NG,HLP ,OS2 IPF and TROFF output files +- Program added to extract documentation from source code and create NG, + HLP, OS2, IPF and TROFF output files - Compile time expression optimizer. - Some preprocessor fixes - Added ADS RDD @@ -64,8 +78,10 @@ Build #31 2000-01-27 - Enhanced Getenv() function - Added //BUILD command line to compiler +---------------------------------------------------------------------- Build #30 September 30 1999 + - RDD support - Support for MEM files - The debugger @@ -94,7 +110,10 @@ Build #30 September 30 1999 - Source code cleanup and formatting - Many new functions, samples and bug fixes +---------------------------------------------------------------------- + Build #29 27 July 1999 + - Support for these compilers: C++ Builder DJGPP for Dos/Windows @@ -114,6 +133,7 @@ Build #29 27 July 1999 - Added support for concatenation operator "-" - Added support to generate runtime errors in functions +---------------------------------------------------------------------- Build #28 18 July 1999 @@ -158,5 +178,5 @@ Build #26 12 June 1999 - Many resolved Bugs - Many new functions - New National language message files -- New TestBank. It compiles ALL Harbour samples +- New TestBank. It compiles ALL Harbour samples - : := can now be used inside expressions (codeblocks)