Chapter 1.  PFE Documentation 0.32.x

Table of Contents

How To Make A Dist
'make doc', 'make dist-doc' and 'make install-doc'
'make rpm' and friends
Tuning The Portable Forth Environment
Loop unrolling in the inner interpreter
Using global register variables
Choosing registers to use
How To Write A PFE Module
The Current State
The Name Of The Module
Create the File And Add It To
What Must Be In The Source File
Semant - advanced words of PFE
Runtime - preparing PFE for call-threading
WordSets in External Modules
External Modules
WordSet Activation
Available Modules
Internal Decisions
The Head.aux Field
The Flag.byte Field
The Head Layout
Non-Const >BODY
StateSmart Words and POSTPONE
Locals in PFE
ANS Locals
Explicit Locals
Special Implementation Strategies
Environment Vocabulary
[defined] / [undefined]
state-smart over exec-only
Quoted-Parse Idea
PFE Threading types
CFA Threaded
CALL Threaded
SBR Threading
SBR-ARG Threading
extra RP or not
Porting SBR-Threading
Choosing an ARG-register
Traditional CPU
RISC w/ LR type CPU
Dirk Zoller's README
What is it?
Why did I do it?
Design objectives
Known Problems
The Underline on ABORT
loading an INCLUDE-file at boot or on the command line
Problems in 0.32.x
The GNU Lesser General Public License (LGPL)
Make A New Dist
how to create a new tarball or series of RPM packages, or to recreate the autoref documentation.
Tuning The Forth VM
explains steps to enhance the speed of the Forth VM
How To Write A PFE Module
explains the steps to create a dynamically loadable pfe extension module
WordSets in External Modules
explains the steps to activate external modules including those pre-linked to PFE.
Some Internal Decisions
explains the structure of the headers of forth words and the reasons for its differences over FIG-forth
StateSmart words
PFE has made many compile-only words statesmart to make life of a regular forth user easier. However, it can mean trouble if used with postpone . Here are the details.
Locals in PFE
PFE uses the return-stack to store local values and enables you to get even alloca()-like buffer areas there, furthering creation of reentrant words even for the case of words handling strings.
Special Implementation Strategies
explains the solutions that were take to common problems in the implementation of an ansiforth'94 compatible system and the means to extend such a system.
a side note on quote-parse
a side note on sbr-threading
Dirk Zoller's README
the README from PFE version 0.9.10
Known Problems
there are some features that people sometimes wonder about.
the License
is the LGPL - the Lesser GNU Public License
references to (online) literature

How To Make A Dist

The toplevel Makefile supports a few targets to create a few types of distribution archives. The most heavily used is really called 'make dist'".

The current project stores the version number of the the project in just one place - the file "pfe.spec" in the toplevel directory. We use a "grep ' ver ' pfe.spec" to extract the line with the version number. This method is used by pfe/ and the dist-targets in the toplevel Makefile use it too.

To make things easier, quite some of the toplevel dist-target look for a subdirectory "pub" in either the project or parent directory. The tar.gz and tar.bz2 archive are placed there - this makes it easier to 'roll' micro-releases for revision control purpose.

The files that go into the source-release-archives are not specified explicitly in the Makefiles (what one would expect from a automake-based project), instead there is a list of file-extensions and file-names that are searched with a call to the posix "find" command. To see the complete list of files that will be rolled into the source-dist, type "make zipfiles". The current dist-scheme assumes that a zip-tool is indeed available to create a, from which a pfe-current.tar.gz is created (which adds the relase-subdir-path), which is the renamed to the release-name.tar.gz itself.

'make doc', 'make dist-doc' and 'make install-doc'

The doc-creation process does not need any information from the configure-process - it works independently. The toplevel doc-targets will forward usually to the doc/Makefile, and it will do so for quite a few other targets as well. The 'make install' will indeed not install these docs (which is a megabyte of html files), so you have to call 'make install-doc'. For the latter, we use a little trick - the install-doc is forwarded to the configure'd Makefile (which knows the configure'd prefix, e.g. /usr/local or /programs), and the configure'd Makefile forward this target in turn to doc/Makefile but adding a makfile-override prefix=@prefix@ - in makefile-speak: '$(MAKE) -C $(srcdir)/../doc/Makefile prefix=$(prefix) [sadly, bsd pmake does not support "-C"]

The doc-tarball created in the doc-subdir (e.g. words.tar, wordsets.tar and doc.tar) can be rolled into a toplevel dist-archive for the doc. This is also needed since the generated docs are so large (around a megabyte of data) and the doc-generation requires perl and a perl-based helper-package xm-tool (from to be made.

'make rpm' and friends

The "make rpm" is currently a bit weird in its assumptions - it looks in the local, parent, parentparent directory for a subdir called "packages". It then copy the "pfe-current.tgz" to "packages/SOURCES/" and call 'rpm -ba pfe.spec'", i.e. rpm-build-all

It is interesting to see that this scheme works for most people who create "rpm" files, but it could be just as well be a bit annoying to some other people.

The debian distro files are currently not shipped with the base pfe.

The windows archive-packages are not fully ready, currently it creates a simple zip-archive with prebuilt binaries for mingw32, but this target is not yet supported - I did this target largely to speed up the development process for this target (cygwin windows-pfe works fine for years).