Imported Upstream version 21

[debian/pforth] / README.txt

README for pForth - a Portable ANS-like Forth written in ANSI 'C'\r
\r
by Phil Burk\r
with Larry Polansky, David Rosenboom and Darren Gibbs.\r
\r
Last updated: 4/6/98 V19\r
\r
Please direct feedback, bug reports, and suggestions to:\r
\r
    philburk@softsynth.com.\r
\r
\r
The author is available for customization of pForth, porting to new\r
\r
platforms, or developing pForth applications on a contractual basis.\r
\r
If interested, contact Phil Burk at philburk@softsynth.com.\r
\r
\r
\r
-- LEGAL NOTICE -----------------------------------------\r
\r
The pForth software code is dedicated to the public domain,\r
and any third party may reproduce, distribute and modify\r
the pForth software code or any derivative works thereof\r
without any compensation or license.  The pForth software\r
code is provided on an "as is" basis without any warranty\r
of any kind, including, without limitation, the implied\r
warranties of merchantability and fitness for a particular\r
purpose and their equivalents under the laws of any jurisdiction.\r
\r
-- How to run PForth ------------------------------------\r
\r
\r
Note: Please refer to "pf_ref.htm" for more complete information.\r
\r
\r
Once you have compiled and built the dictionary, just enter:\r
     pforth\r
\r
\r
To compile source code files use:    INCLUDE filename\r
\r
To create a custom dictionary enter in pForth:\r
        c" newfilename.dic" SAVE-FORTH\r
The name must end in ".dic".\r
\r
To run PForth with the new dictionary enter in the shell:\r
        pforth -dnewfilename.dic\r
\r
To run PForth and automatically include a forth file:\r
        pforth myprogram.fth\r
\r
-- How to run PForth ------------------------------------\r
\r
You can test the Forth without loading a dictionary\r
which might be necessary if the dictionary can't be built.\r
\r
\r
Enter:   pforth -i\r
In pForth, enter:    3 4 + .\r
In pForth, enter:    loadsys\r
In pForth, enter:    10  0  do i . loop\r
\r
PForth comes with a small test suite.  To test the Core words,\r
you can use the coretest developed by John Hayes.\r
\r
Enter:  pforth\r
Enter:  include tester.fth\r
Enter:  include coretest.fth\r
\r
To run the other tests, enter:\r
\r
        pforth t_corex.fth\r
        pforth t_strings.fth\r
        pforth t_locals.fth\r
        pforth t_alloc.fth\r
        \r
They will report the number of tests that pass or fail.\r
\r
-- Version History --------------------------------------\r
\r
V1 - 5/94\r
        - built pForth from various Forths including HMSL\r
        \r
V2 - 8/94\r
        - made improvements necessary for use with M2 Verilog testing\r
        \r
V3 - 3/1/95\r
        - Added support for embedded systems: PF_NO_FILEIO\r
        and PF_NO_MALLOC.\r
        - Fixed bug in dictionary loader that treated HERE as name relative.\r
\r
V4 - 3/6/95\r
        - Added smart conditionals to allow IF THEN DO LOOP etc.\r
          outside colon definitions.\r
        - Fixed RSHIFT, made logical.\r
        - Added ARSHIFT for arithmetic shift.\r
        - Added proper M*\r
        - Added <> U> U<\r
        - Added FM/MOD SM/REM /MOD MOD */ */MOD\r
        - Added +LOOP EVALUATE UNLOOP EXIT\r
        - Everything passes "coretest.fth" except UM/MOD FIND and WORD\r
\r
V5 - 3/9/95\r
        - Added pfReportError()\r
        - Fixed problem with NumPrimitives growing and breaking dictionaries\r
        - Reduced size of saved dictionaries, 198K -> 28K in one instance\r
        - Funnel all terminal I/O through ioKey() and ioEmit()\r
        - Removed dependencies on printf() except for debugging\r
        \r
V6 - 3/16/95\r
        - Added floating point\r
        - Changed NUMBER? to return a numeric type\r
        - Support double number entry, eg.   234.  -> 234 0\r
        \r
V7 - 4/12/95\r
        - Converted to 3DO Teamware environment\r
        - Added conditional compiler [IF] [ELSE] [THEN], use like #if\r
        - Fixed W->S B->S for positive values\r
        - Fixed ALLOCATE FREE validation.  Was failing on some 'C' compilers.\r
        - Added FILE-SIZE\r
        - Fixed ERASE, now fills with zero instead of BL\r
\r
V8 - 5/1/95\r
        - Report line number and line dump when INCLUDE aborts\r
        - Abort if stack depth changes in colon definition. Helps\r
          detect unbalanced conditionals (IF without THEN).\r
        - Print bytes added by include.  Helps determine current file.\r
        - Added RETURN-CODE which is returned to caller, eg. UNIX shell.\r
        - Changed Header and Code sizes to 60000 and 150000\r
        - Added check for overflowing dictionary when creating secondaries.\r
        \r
V9 - 10/13/95\r
        - Cleaned up and documented for alpha release.\r
        - Added EXISTS?\r
        - compile floats.fth if F* exists\r
        - got PF_NO_SHELL working\r
        - added TURNKEY to build headerless dictionary apps\r
        - improved release script and rlsMakefile\r
        - added FS@ and FS! for FLPT structure members\r
        \r
V10 - 3/21/96\r
        - Close nested source files when INCLUDE aborts.\r
        - Add PF_NO_CLIB option to reduce OS dependencies.\r
        - Add CREATE-FILE, fix R/W access mode for OPEN-FILE.\r
        - Use PF_FLOAT instead of FLOAT to avoid DOS problem.\r
        - Add PF_HOST_DOS for compilation control.\r
        - Shorten all long file names to fit in the 8.3 format\r
          required by some primitive operating systems. My\r
          apologies to those with modern computers who suffer\r
          as a result.  ;-)\r
\r
V11 - 11/14/96\r
        - Added support for AUTO.INIT and AUTO.TERM.  These are called\r
          automagically when the Forth starts and quits.\r
        - Change all int to int32.\r
        - Changed DO LOOP to ?DO LOOP in ENDCASE and LV.MATCH\r
          to fix hang when zero local variables.\r
        - Align long word members in :STRUCT to avoid bus errors.\r
        \r
V12 - 12/1/96\r
        - Advance pointers in pfCopyMemory() and pfSetMemory()\r
          to fix PF_NO_CLIB build.\r
        - Increase size of array for PF_NO_MALLOC\r
        - Eliminate many warnings involving type casts and (const char *)\r
        - Fix error recovery in dictionary creation.\r
        - Conditionally eliminate some include files for embedded builds.\r
        - Cleanup some test files.\r
\r
V13 - 12/15/96\r
        - Add "extern 'C' {" to pf_mem.h for C++\r
        - Separate PF_STATIC_DIC from PF_NO_FILEIO so that we can use a static\r
          dictionary but also have file I/O.\r
        - Added PF_USER_FILEIO, PF_USER_CHARIO, PF_USER_CLIB.\r
        - INCLUDE now aborts if file not found.\r
        - Add +-> which allows you to add to a local variable, like +! .\r
        - VALUE now works properly as a self fetching constant.\r
        - Add CODE-SIZE and HEADERS-SIZE which lets you resize\r
          dictionary saved using SAVE-FORTH.\r
        - Added FILE?. Enter "FILE? THEN" to see what files THEN is defined in.\r
        - Fixed bug in local variables that caused problems if compilation\r
          aborted in a word with local variables.\r
        - Added SEE which "disassembles" Forth words. See "see.fth".\r
        - Added PRIVATE{ which can be used to hide low level support\r
          words.  See "private.fth".\r
        \r
V14 - 12/23/96\r
        * pforth command now requires -d before dictionary name.\r
                Eg.   pforth -dcustom.dic test.fth\r
        * PF_USER_* now need to be defined as include file names.\r
        * PF_USER_CHARIO now requires different functions to be defined.\r
                See "csrc/pf_io.h".\r
        - Moved pfDoForth() from pf_main.c to pf_core.c to simplify\r
          file with main().\r
        - Fix build with PF_NO_INIT\r
        - Makefile now has target for embedded dictionary, "gmake pfemb".\r
        \r
V15 - 2/15/97\r
        * If you use PF_USER_FILEIO, you must now define PF_STDIN and PF_STDOUT\r
          among other additions. See "pf_io.h".\r
        * COMPARE now matches ANS STRING word set!\r
        - Added PF_USER_INC1 and PF_USER_INC2 for optional includes\r
          and host customization. See "pf_all.h".\r
        - Fixed more warnings.\r
        - Fixed >NAME and WORDS for systems with high "negative" addresses.\r
        - Added WORDS.LIKE utility.  Enter:   WORDS.LIKE EMIT\r
        - Added stack check after every word in high level interpreter.\r
          Enter QUIT to enter high level interpreter which uses this feature.\r
        - THROW will no longer crash if not using high level interpreter.\r
        - Isolated all host dependencies into "pf_unix.h", "pf_win32.h",\r
          "pf_mac.h", etc.  See "pf_all.h".\r
        - Added tests for CORE EXT, STRINGS words sets.\r
        - Added SEARCH\r
        - Fixed WHILE and REPEAT for multiple WHILEs.\r
        - Fixed .( ) for empty strings.\r
        - Fixed FATAN2 which could not compile on some systems (Linux gcc).\r
\r
V16\r
        * Define PF_USER_CUSTOM if you are defining your own custom\r
          'C' glue routines.  This will ifndef the published example.\r
        - Fixed warning in pf_cglue.c.\r
        - Fixed SDAD in savedicd.fth.  It used to generate bogus 'C' code\r
          if called when (BASE != 10), as in HEX mode.\r
        - Fixed address comparisons in forget.fth and private.fth for\r
          addresses above 0x80000000. Must be unsigned.\r
        - Call FREEZE at end of system.fth to initialize rfence.\r
        - Fixed 0.0 F. which used to leave 0.0 on FP stack.\r
        - Added FPICK ( n -- ) ( i*f -- i*f f[n] )\r
        - .S now prints hex numbers as unsigned.\r
        - Fixed internal number to text conversion for unsigned nums.\r
\r
V17\r
        - Fixed input of large floats.  0.7071234567 F.  used to fail.\r
\r
V18\r
        - Make FILL a 'C' primitive.\r
        - optimized locals with (1_LOCAL@)\r
        - optimized inner interpreter by 15%\r
        - fix tester.fth failures\r
        - Added define for PF_KEY_ECHOS which turns off echo in ACCEPT if defined.\r
        - Fixed MARKER. Was equivalent to ANEW instead of proper ANS definition.\r
        - Fixed saving and restoring of TIB when nesting include files.\r
\r
V19  4/98\r
\r
        - Warn if local var name matches dictionary, : foo { count -- } ;\r
        - TO -> and +-> now parse input stream. No longer use to-flag.\r
        - TO -> and +-> now give error if used with non-immediate word.\r
        - Added (FLITERAL) support to SEE.\r
        - Aded TRACE facility for single step debugging of Forth words.\r
        - Added stub for ?TERMINAL and KEY? for embedded systems.\r
        - Added PF_NO_GLOBAL_INIT for no reliance on global initialization.\r
        - Added PF_USER_FLOAT for customization of FP support.\r
        - Added floating point to string conversion words (F.) (FS.) (FE.)\r
            For example:   : F.   (F.)  TYPE  SPACE  ;\r
        - Reversed order that values are placed on return stack in 2>R\r
          so that it matches ANS standard.  2>R is now same as SWAP >R >R\r
          Thank you Leo Wong for reporting this bug.\r
\r
        - Added PF_USER_INIT and PF_USER_TERM for user definable init and term calls.\r
\r
        - FIXED memory leak in pfDoForth()\r
\r
V20\r
    - Expand PAD for ConvertNumberToText so "-1 binary .s" doesn't crash.\r
      Thank you Michael Connor of Vancouver for reporting this bug.\r
\r
    - Removed FDROP in REPRESENT to fix stack underflow after "0.0 F.".\r
      Thank you Jim Rosenow of Minnesota for reporting this bug.\r
        - Changed pfCharToLower to function to prevent macro expansion bugs under VXWORKS\r
      Thank you Jim Rosenow of Minnesota for reporting this bug.\r
\r
        - "0.0 F~" now checks actual binary encoding of floats. Before this it used to just\r
          compare value which was incorrect. Now "0.0 -0.0 0.0 F~" returns FALSE.\r
\r
        - Fixed definition of INPUT$ in tutorial.\r
      Thank you Hampton Miller of California for reporting this bug.\r
\r
        - Added support for producing a target dictionary with a different\r
          Endian-ness than the host CPU.  See PF_BIG_ENDIAN_DIC and PF_LITTLE_ENDIAN_DIC.\r
\r
        - PForth kernel now comes up in a mode that uses BASE for numeric input when\r
          started with "-i" option.  It used to always consider numeric input as HEX.\r
          Initial BASE is decimal.  \r
\r
V21\r
        - Fixed some compiler warnings.\r
\r
Enjoy,\r
Phil Burk\r