git.gag.com Git - debian/pforth/blob - README.md

   1 # PForth - a Portable ANS-like Forth written in ANSI 'C'
   2
   3 by Phil Burk
   4 with Larry Polansky, David Rosenboom and Darren Gibbs.
   5 Support for 64-bit cells by Aleksej Saushev.
   6
   7 Last updated: November 27, 2022
   8
   9 Portable Forth written in 'C' for most 32 and 64-bit platforms.
  10
  11 PForth is written in 'C' and can be easily ported to new 32 and 64-bit platforms.
  12 It only needs character input and output functions to operate and, therefore, does not require an operating system.
  13 This makes it handy for bringing up and testing embedded systems.
  14
  15 PForth also works on desktops including Windows, Mac and Linux and supports command line history.
  16 This lets you develop hardware tests on a desktop before trying them on your embedded system.
  17 But pForth is not a rich and friendly desktop programming environment.
  18 There are no GUI tools for developing desktop applications. PForth is lean and mean and optimized for portability.
  19
  20 PForth has a tool for compiling code on a desktop, then exporting the dictionary in big or little endian format as 'C' source code.
  21 This lets you compile tests for an embedded system that does not have file I/O.
  22
  23 PForth is based on ANSI-Forth but is not 100% compatible.
  24
  25 Code for pForth is maintained on GitHub at:
  26   https://github.com/philburk/pforth
  27
  28 Documentation for pForth at:
  29   http://www.softsynth.com/pforth/
  30
  31 To report bugs or request features please file a GitHub Issue.
  32
  33 For questions or general discussion please use the pForth forum at:
  34   http://groups.google.com/group/pforthdev
  35
  36 ## LEGAL NOTICE
  37
  38 Permission to use, copy, modify, and/or distribute this
  39 software for any purpose with or without fee is hereby granted.
  40
  41 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
  42 WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
  43 WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  44 THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
  45 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  46 FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
  47 CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  48 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  49
  50 ## Contents of SDK
  51
  52     platforms - tools for building pForth on various platforms
  53     platforms/unix - Makefile for unix
  54
  55     csrc - pForth kernel in ANSI 'C'
  56     csrc/pf_main.c - main() application for a standalone Forth
  57     csrc/stdio - I/O code using basic stdio for generic platforms
  58     csrc/posix - I/O code for Posix platform
  59     csrc/win32 - I/O code for basic WIN32 platform
  60     csrc/win32_console - I/O code for WIN32 console that supports command line history
  61
  62     fth - Forth code
  63     fth/util - utility functions
  64
  65 ## How to Build pForth
  66
  67 Building pForth involves two steps:
  68 1) building the C based Forth kernel
  69 2) building the Forth dictionary file using: ./pforth -i system.fth
  70 3) optional build of standalone executable with built-in dictionary
  71
  72 We have provided build scripts to simplify this process.
  73
  74 On Unix and MacOS using Makefile:
  75
  76     cd platforms/unix
  77     make all
  78     ./pforth_standalone
  79
  80 For more details, see the [Wiki](https://github.com/philburk/pforth/wiki/Compiling-on-Unix)
  81
  82 Using CMake:
  83
  84     cmake .
  85     make
  86     cd fth
  87     ./pforth_standalone
  88
  89 For embedded systems, see the pForth reference manual at:
  90
  91   http://www.softsynth.com/pforth/pf_ref.php
  92
  93 ## How to Run pForth
  94
  95 To run the all-in-one pForth enter:
  96
  97     ./pforth_standalone
  98
  99 OR to run using the dictionary file enter:
 100
 101     pforth
 102
 103 Quick check of Forth:
 104
 105     3 4 + .
 106     words
 107     bye
 108
 109 To compile source code files use:
 110
 111     INCLUDE filename
 112
 113 To create a custom dictionary enter in pForth:
 114
 115     c" newfilename.dic" SAVE-FORTH
 116
 117 The name must end in ".dic".
 118
 119 To run PForth with the new dictionary enter in the shell:
 120
 121     pforth -dnewfilename.dic
 122
 123 To run PForth and automatically include a forth file:
 124     pforth myprogram.fth
 125
 126 ## How to Test pForth
 127
 128 PForth comes with a small test suite.  To test the Core words,
 129 you can use the coretest developed by John Hayes.
 130
 131 On Unix and MacOS using Makefile:
 132
 133     cd platforms/unix
 134     make test
 135
 136 Using CMake
 137
 138     cd fth
 139     ./pforth
 140     include tester.fth
 141     include coretest.fth
 142
 143 To run the other tests, enter:
 144
 145     pforth t_corex.fth
 146     pforth t_strings.fth
 147     pforth t_locals.fth
 148     pforth t_alloc.fth
 149
 150 They will report the number of tests that pass or fail.
 151
 152 You can also test pForth kernel without loading a dictionary.
 153 Only the primitive words defined in C will be available.
 154 This might be necessary if the dictionary can't be built.
 155
 156     ./pforth -i
 157     3 4 + .
 158     23 77 swap .s
 159     loadsys