This is gforth.info, produced by makeinfo version 4.0 from gforth.texi.

INFO-DIR-SECTION GNU programming tools
START-INFO-DIR-ENTRY
* Gforth: (gforth).             A fast interpreter for the Forth language.
END-INFO-DIR-ENTRY

   This file documents Gforth 0.5.0

   Copyright (C) 1995-2000 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
 are preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this      manual under the conditions for verbatim copying, provided
also that the      sections entitled "Distribution" and "General Public
License" are      included exactly as in the original, and provided
that the entire      resulting derived work is distributed under the
terms of a permission      notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual      into another language, under the above conditions for
modified versions,      except that the sections entitled
"Distribution" and "General Public      License" may be included in a
translation approved by the author instead      of in the original
English.


File: gforth.info,  Node: Performance,  Prev: Primitives,  Up: Engine

Performance
===========

   On RISCs the Gforth engine is very close to optimal; i.e., it is
usually impossible to write a significantly faster engine.

   On register-starved machines like the 386 architecture processors
improvements are possible, because `gcc' does not utilize the registers
as well as a human, even with explicit register declarations; e.g.,
Bernd Beuster wrote a Forth system fragment in assembly language and
hand-tuned it for the 486; this system is 1.19 times faster on the
Sieve benchmark on a 486DX2/66 than Gforth compiled with `gcc-2.6.3'
with `-DFORCE_REG'.  The situation has improved with gcc-2.95 and
gforth-0.4.9; now the most important virtual machine registers fit in
real registers (and we can even afford to use the TOS optimization),
resulting in a speedup of 1.14 on the sieve over the earlier results.

   The potential advantage of assembly language implementations is not
necessarily realized in complete Forth systems: We compared Gforth-0.4.9
(direct threaded, compiled with `gcc-2.95.1' and `-DFORCE_REG') with
Win32Forth 1.2093 (newer versions are reportedly much faster), LMI's NT
Forth (Beta, May 1994) and Eforth (with and without peephole (aka
pinhole) optimization of the threaded code); all these systems were
written in assembly language. We also compared Gforth with three
systems written in C: PFE-0.9.14 (compiled with `gcc-2.6.3' with the
default configuration for Linux: `-O2 -fomit-frame-pointer -DUSE_REGS
-DUNROLL_NEXT'), ThisForth Beta (compiled with `gcc-2.6.3 -O3
-fomit-frame-pointer'; ThisForth employs peephole optimization of the
threaded code) and TILE (compiled with `make opt'). We benchmarked
Gforth, PFE, ThisForth and TILE on a 486DX2/66 under Linux. Kenneth
O'Heskin kindly provided the results for Win32Forth and NT Forth on a
486DX2/66 with similar memory performance under Windows NT. Marcel
Hendrix ported Eforth to Linux, then extended it to run the benchmarks,
added the peephole optimizer, ran the benchmarks and reported the
results.

   We used four small benchmarks: the ubiquitous Sieve; bubble-sorting
and matrix multiplication come from the Stanford integer benchmarks and
have been translated into Forth by Martin Fraeman; we used the versions
included in the TILE Forth package, but with bigger data set sizes; and
a recursive Fibonacci number computation for benchmarking calling
performance. The following table shows the time taken for the benchmarks
scaled by the time taken by Gforth (in other words, it shows the speedup
factor that Gforth achieved over the other systems).

     relative      Win32-    NT       eforth       This-
       time  Gforth Forth Forth eforth  +opt   PFE Forth  TILE
     sieve     1.00  1.60  1.32   1.60  0.98  1.82  3.67  9.91
     bubble    1.00  1.55  1.66   1.75  1.04  1.78        4.58
     matmul    1.00  1.71  1.57   1.69  0.86  1.83        4.74
     fib       1.00  1.76  1.54   1.41  1.00  2.01  3.45  4.96

   You may be quite surprised by the good performance of Gforth when
compared with systems written in assembly language. One important reason
for the disappointing performance of these other systems is probably
that they are not written optimally for the 486 (e.g., they use the
`lods' instruction). In addition, Win32Forth uses a comfortable, but
costly method for relocating the Forth image: like `cforth', it
computes the actual addresses at run time, resulting in two address
computations per `NEXT' (*note Image File Background::).

   Only Eforth with the peephole optimizer performs comparable to
Gforth. The speedups achieved with peephole optimization of threaded
code are quite remarkable. Adding a peephole optimizer to Gforth should
cause similar speedups.

   The speedup of Gforth over PFE, ThisForth and TILE can be easily
explained with the self-imposed restriction of the latter systems to
standard C, which makes efficient threading impossible (however, the
measured implementation of PFE uses a GNU C extension: *note Defining
Global Register Variables: (gcc.info)Global Reg Vars.).  Moreover,
current C compilers have a hard time optimizing other aspects of the
ThisForth and the TILE source.

   The performance of Gforth on 386 architecture processors varies
widely with the version of `gcc' used. E.g., `gcc-2.5.8' failed to
allocate any of the virtual machine registers into real machine
registers by itself and would not work correctly with explicit register
declarations, giving a 1.5 times slower engine (on a 486DX2/66 running
the Sieve) than the one measured above.

   Note that there have been several releases of Win32Forth since the
release presented here, so the results presented above may have little
predictive value for the performance of Win32Forth today (results for
the current release on an i486DX2/66 are welcome).

   In `Translating Forth to Efficient C
(http://www.complang.tuwien.ac.at/papers/ertl&maierhofer95.ps.gz)' by
M. Anton Ertl and Martin Maierhofer (presented at EuroForth '95), an
indirect threaded version of Gforth is compared with Win32Forth, NT
Forth, PFE, ThisForth, and several native code systems; that version of
Gforth is slower on a 486 than the direct threaded version used here.
You can find a newer version of these measurements at
`http://www.complang.tuwien.ac.at/forth/performance.html'. You can find
numbers for Gforth on various machines in `Benchres'.


File: gforth.info,  Node: Binding to System Library,  Next: Cross Compiler,  Prev: Engine,  Up: Top

Binding to System Library
*************************


File: gforth.info,  Node: Cross Compiler,  Next: Bugs,  Prev: Binding to System Library,  Up: Top

Cross Compiler
**************

   The cross compiler is used to bootstrap a Forth kernel. Since Gforth
is mostly written in Forth, including crucial parts like the outer
interpreter and compiler, it needs compiled Forth code to get started.
The cross compiler allows to create new images for other architectures,
even running under another Forth system.

* Menu:

* Using the Cross Compiler::
* How the Cross Compiler Works::


File: gforth.info,  Node: Using the Cross Compiler,  Next: How the Cross Compiler Works,  Prev: Cross Compiler,  Up: Cross Compiler

Using the Cross Compiler
========================

   The cross compiler uses a language that resembles Forth, but isn't.
The main difference is that you can execute Forth code after definition,
while you usually can't execute the code compiled by cross, because the
code you are compiling is typically for a different computer than the
one you are compiling on.

   The Makefile is already set up to allow you to create kernels for new
architectures with a simple make command. The generic kernels using the
GCC compiled virtual machine are created in the normal build process
with `make'. To create a embedded Gforth executable for e.g. the 8086
processor (running on a DOS machine), type

     make kernl-8086.fi

   This will use the machine description from the `arch/8086' directory
to create a new kernel. A machine file may look like that:

     \ Parameter for target systems                         06oct92py
     
         4 Constant cell             \ cell size in bytes
         2 Constant cell<<           \ cell shift to bytes
         5 Constant cell>bit         \ cell shift to bits
         8 Constant bits/char        \ bits per character
         8 Constant bits/byte        \ bits per byte [default: 8]
         8 Constant float            \ bytes per float
         8 Constant /maxalign        \ maximum alignment in bytes
     false Constant bigendian        \ byte order
     ( true=big, false=little )
     
     include machpc.fs               \ feature list

   This part is obligatory for the cross compiler itself, the feature
list is used by the kernel to conditionally compile some features in
and out, depending on whether the target supports these features.

   There are some optional features, if you define your own primitives,
have an assembler, or need special, nonstandard preparation to make the
boot process work. `asm-include' includes an assembler, `prims-include'
includes primitives, and `>boot' prepares for booting.

     : asm-include    ." Include assembler" cr
       s" arch/8086/asm.fs" included ;
     
     : prims-include  ." Include primitives" cr
       s" arch/8086/prim.fs" included ;
     
     : >boot          ." Prepare booting" cr
       s" ' boot >body into-forth 1+ !" evaluate ;

   These words are used as sort of macro during the cross compilation in
the file `kernel/main.fs'. Instead of using these macros, it would be
possible -- but more complicated -- to write a new kernel project file,
too.

   `kernel/main.fs' expects the machine description file name on the
stack; the cross compiler itself (`cross.fs') assumes that either
`mach-file' leaves a counted string on the stack, or `machine-file'
leaves an address, count pair of the filename on the stack.

   The feature list is typically controlled using `SetValue', generic
files that are used by several projects can use `DefaultValue' instead.
Both functions work like `Value', when the value isn't defined, but
`SetValue' works like `to' if the value is defined, and `DefaultValue'
doesn't set anything, if the value is defined.

     \ generic mach file for pc gforth                       03sep97jaw
     
     true DefaultValue NIL  \ relocating
     
     >ENVIRON
     
     true DefaultValue file          \ controls the presence of the
                                     \ file access wordset
     true DefaultValue OS            \ flag to indicate a operating system
     
     true DefaultValue prims         \ true: primitives are c-code
     
     true DefaultValue floating      \ floating point wordset is present
     
     true DefaultValue glocals       \ gforth locals are present
                                     \ will be loaded
     true DefaultValue dcomps        \ double number comparisons
     
     true DefaultValue hash          \ hashing primitives are loaded/present
     
     true DefaultValue xconds        \ used together with glocals,
                                     \ special conditionals supporting gforths'
                                     \ local variables
     true DefaultValue header        \ save a header information
     
     true DefaultValue backtrace     \ enables backtrace code
     
     false DefaultValue ec
     false DefaultValue crlf
     
     cell 2 = [IF] &32 [ELSE] &256 [THEN] KB DefaultValue kernel-size
     
     &16 KB          DefaultValue stack-size
     &15 KB &512 +   DefaultValue fstack-size
     &15 KB          DefaultValue rstack-size
     &14 KB &512 +   DefaultValue lstack-size


File: gforth.info,  Node: How the Cross Compiler Works,  Prev: Using the Cross Compiler,  Up: Cross Compiler

How the Cross Compiler Works
============================


File: gforth.info,  Node: Bugs,  Next: Origin,  Prev: Cross Compiler,  Up: Top

Bugs
****

   Known bugs are described in the file `BUGS' in the Gforth
distribution.

   If you find a bug, please send a bug report to <bug-gforth@gnu.org>.
A bug report should include this information:

   * A program (or a sequence of keyboard commands) that reproduces the
     bug.

   * A description of what you think constitutes the buggy behaviour.

   * The Gforth version used (it is announced at the start of an
     interactive Gforth session).

   * The machine and operating system (on Unix systems `uname -a' will
     report this information).

   * The installation options (you can find the configure options at the
     start of `config.status') and configuration (`configure' output or
     `config.cache').

   * A complete list of changes (if any) you (or your installer) have
     made to the Gforth sources.

   For a thorough guide on reporting bugs read *Note How to Report
Bugs: (gcc.info)Bug Reporting.


File: gforth.info,  Node: Origin,  Next: Forth-related information,  Prev: Bugs,  Up: Top

Authors and Ancestors of Gforth
*******************************

Authors and Contributors
========================

   The Gforth project was started in mid-1992 by Bernd Paysan and Anton
Ertl. The third major author was Jens Wilke.  Neal Crook contributed a
lot to the manual.  Assemblers and disassemblers were contributed by
Andrew McKewan, Christian Pirker, and Bernd Thallner.  Lennart Benschop
(who was one of Gforth's first users, in mid-1993) and Stuart Ramsden
inspired us with their continuous feedback. Lennart Benshop contributed
`glosgen.fs', while Stuart Ramsden has been working on automatic
support for calling C libraries. Helpful comments also came from Paul
Kleinrubatscher, Christian Pirker, Dirk Zoller, Marcel Hendrix, John
Wavrik, Barrie Stott, Marc de Groot, Jorge Acerada, Bruce Hoyt, and
Robert Epprecht. Since the release of Gforth-0.2.1 there were also
helpful comments from many others; thank you all, sorry for not listing
you here (but digging through my mailbox to extract your names is on my
to-do list).

   Gforth also owes a lot to the authors of the tools we used (GCC, CVS,
and autoconf, among others), and to the creators of the Internet: Gforth
was developed across the Internet, and its authors did not meet
physically for the first 4 years of development.

Pedigree
========

   Gforth descends from bigFORTH (1993) and fig-Forth.  Of course, a
significant part of the design of Gforth was prescribed by ANS Forth.

   Bernd Paysan wrote bigFORTH, a descendent from TurboForth, an
unreleased 32 bit native code version of VolksForth for the Atari ST,
written mostly by Dietrich Weineck.

   VolksForth was written by Klaus Schleisiek, Bernd Pennemann, Georg
Rehfeld and Dietrich Weineck for the C64 (called UltraForth there) in
the mid-80s and ported to the Atari ST in 1986.  It descends from F83.

   Henry Laxen and Mike Perry wrote F83 as a model implementation of the
Forth-83 standard. !! Pedigree? When?

   A team led by Bill Ragsdale implemented fig-Forth on many processors
in 1979. Robert Selzer and Bill Ragsdale developed the original
implementation of fig-Forth for the 6502 based on microForth.

   The principal architect of microForth was Dean Sanderson. microForth
was FORTH, Inc.'s first off-the-shelf product. It was developed in 1976
for the 1802, and subsequently implemented on the 8080, the 6800 and the
Z80.

   All earlier Forth systems were custom-made, usually by Charles Moore,
who discovered (as he puts it) Forth during the late 60s. The first full
Forth existed in 1971.

   A part of the information in this section comes from `The Evolution
of Forth (http://www.forth.com/Content/History/History1.htm)' by
Elizabeth D. Rather, Donald R. Colburn and Charles H. Moore, presented
at the HOPL-II conference and preprinted in SIGPLAN Notices 28(3),
1993.  You can find more historical and genealogical information about
Forth there.


File: gforth.info,  Node: Forth-related information,  Next: Word Index,  Prev: Origin,  Up: Top

Other Forth-related information
*******************************

   There is an active news group (comp.lang.forth) discussing Forth
(including Gforth) and Forth-related issues. Its FAQs
(http://www.complang.tuwien.ac.at/forth/faq/faq-general-2.html)
(frequently asked questions and their answers) contains a lot of
information on Forth.  You should read it before posting to
comp.lang.forth.

   The ANS Forth standard is most usable in its HTML form
(http://www.taygeta.com/forth/dpans.html).

