version 1.43, 1997/02/01 14:59:30
|
version 1.48, 1997/04/10 15:00:06
|
Line 3
|
Line 3
|
@comment %**start of header (This is for running Texinfo on a region.) |
@comment %**start of header (This is for running Texinfo on a region.) |
@setfilename gforth.info |
@setfilename gforth.info |
@settitle Gforth Manual |
@settitle Gforth Manual |
|
@dircategory GNU programming tools |
|
@direntry |
|
* Gforth: (gforth). A fast interpreter for the Forth language. |
|
@end direntry |
@comment @setchapternewpage odd |
@comment @setchapternewpage odd |
@comment %**end of header (This is for running Texinfo on a region.) |
@comment %**end of header (This is for running Texinfo on a region.) |
|
|
Line 99 personal machines. This manual correspon
|
Line 103 personal machines. This manual correspon
|
* Concept Index:: A menu covering many topics |
* Concept Index:: A menu covering many topics |
@end menu |
@end menu |
|
|
@node License, Preface, Top, Top |
@node License, Goals, Top, Top |
@unnumbered GNU GENERAL PUBLIC LICENSE |
@unnumbered GNU GENERAL PUBLIC LICENSE |
@center Version 2, June 1991 |
@center Version 2, June 1991 |
|
|
Line 492 library. If this is what you want to do
|
Line 496 library. If this is what you want to do
|
Public License instead of this License. |
Public License instead of this License. |
|
|
@iftex |
@iftex |
@node Preface, Goals, License, Top |
|
@comment node-name, next, previous, up |
|
@unnumbered Preface |
@unnumbered Preface |
@cindex Preface |
@cindex Preface |
This manual documents Gforth. The reader is expected to know |
This manual documents Gforth. The reader is expected to know |
Line 501 Forth. This manual is primarily a refere
|
Line 503 Forth. This manual is primarily a refere
|
for introductory material. |
for introductory material. |
@end iftex |
@end iftex |
|
|
@node Goals, Other Books, Preface, Top |
@node Goals, Other Books, License, Top |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
@chapter Goals of Gforth |
@chapter Goals of Gforth |
@cindex Goals |
@cindex Goals |
Line 566 can also get it from Global Engineering
|
Line 568 can also get it from Global Engineering
|
for publication is available electronically and for free in some MS Word |
for publication is available electronically and for free in some MS Word |
format, and it has been converted to HTML. Some pointers to these |
format, and it has been converted to HTML. Some pointers to these |
versions can be found through |
versions can be found through |
@*@file{http://www.complang.tuwien.ac.at/projects/forth.html}. |
@*@url{http://www.complang.tuwien.ac.at/projects/forth.html}. |
|
|
@cindex introductory book |
@cindex introductory book |
@cindex book, introductory |
@cindex book, introductory |
Line 1371 The index of the innermost loop can be a
|
Line 1373 The index of the innermost loop can be a
|
of the next loop with @code{j}, and the index of the third loop with |
of the next loop with @code{j}, and the index of the third loop with |
@code{k}. |
@code{k}. |
|
|
|
doc-i |
|
doc-j |
|
doc-k |
|
|
The loop control data are kept on the return stack, so there are some |
The loop control data are kept on the return stack, so there are some |
restrictions on mixing return stack accesses and counted loop |
restrictions on mixing return stack accesses and counted loop |
words. E.g., if you put values on the return stack outside the loop, you |
words. E.g., if you put values on the return stack outside the loop, you |
Line 1607 implemented the ANS Forth locals wordset
|
Line 1613 implemented the ANS Forth locals wordset
|
The ideas in this section have also been published in the paper |
The ideas in this section have also been published in the paper |
@cite{Automatic Scoping of Local Variables} by M. Anton Ertl, presented |
@cite{Automatic Scoping of Local Variables} by M. Anton Ertl, presented |
at EuroForth '94; it is available at |
at EuroForth '94; it is available at |
@*@file{http://www.complang.tuwien.ac.at/papers/ertl94l.ps.gz}. |
@*@url{http://www.complang.tuwien.ac.at/papers/ertl94l.ps.gz}. |
|
|
@menu |
@menu |
* Gforth locals:: |
* Gforth locals:: |
Line 4392 convention, we use the extension @code{.
|
Line 4398 convention, we use the extension @code{.
|
* Image File Background:: Why have image files? |
* Image File Background:: Why have image files? |
* Non-Relocatable Image Files:: don't always work. |
* Non-Relocatable Image Files:: don't always work. |
* Data-Relocatable Image Files:: are better. |
* Data-Relocatable Image Files:: are better. |
* Fully Relocatable Image Files:: are hard to create. |
* Fully Relocatable Image Files:: better yet. |
* Stack and Dictionary Sizes:: Setting the default sizes for an image. |
* Stack and Dictionary Sizes:: Setting the default sizes for an image. |
* Running Image Files:: @code{gforth -i @var{file}} or @var{file}. |
* Running Image Files:: @code{gforth -i @var{file}} or @var{file}. |
* Modifying the Startup Sequence:: and turnkey applications. |
* Modifying the Startup Sequence:: and turnkey applications. |
Line 4403 convention, we use the extension @code{.
|
Line 4409 convention, we use the extension @code{.
|
@cindex image file background |
@cindex image file background |
|
|
Our Forth system consists not only of primitives, but also of |
Our Forth system consists not only of primitives, but also of |
definitions written in Forth. Since the Forth compiler itself belongs |
definitions written in Forth. Since the Forth compiler itself belongs to |
to those definitions, it is not possible to start the system with the |
those definitions, it is not possible to start the system with the |
primitives and the Forth source alone. Therefore we provide the Forth |
primitives and the Forth source alone. Therefore we provide the Forth |
code as an image file in nearly executable form. At the start of the |
code as an image file in nearly executable form. At the start of the |
system a C routine loads the image file into memory, sets up the |
system a C routine loads the image file into memory, optionally |
memory (stacks etc.) according to information in the image file, and |
relocates the addresses, then sets up the memory (stacks etc.) according |
starts executing Forth code. |
to information in the image file, and starts executing Forth code. |
|
|
The image file variants represent different compromises between the |
The image file variants represent different compromises between the |
goals of making it easy to generate image files and making them |
goals of making it easy to generate image files and making them |
Line 4422 files are data relocatable without furth
|
Line 4428 files are data relocatable without furth
|
(one addition per memory access). |
(one addition per memory access). |
|
|
@cindex relocation at load-time |
@cindex relocation at load-time |
Our loader performs relocation at image load time. The loader also has |
By contrast, our loader performs relocation at image load time. The |
to replace tokens standing for primitive calls with the appropriate |
loader also has to replace tokens standing for primitive calls with the |
code-field addresses (or code addresses in the case of direct |
appropriate code-field addresses (or code addresses in the case of |
threading). |
direct threading). |
|
|
There are three kinds of image files, with different degrees of |
There are three kinds of image files, with different degrees of |
relocatability: non-relocatable, data-relocatable, and fully relocatable |
relocatability: non-relocatable, data-relocatable, and fully relocatable |
Line 4444 cannot represent @code{ALLOCATE}d memory
|
Line 4450 cannot represent @code{ALLOCATE}d memory
|
them). And the contents of the stacks are not represented, either. |
them). And the contents of the stacks are not represented, either. |
|
|
@item |
@item |
The only kinds of relocation supported are: the addition of the same |
The only kinds of relocation supported are: adding the same offset to |
offset to all cells that represent data addresses; and the replacement of |
all cells that represent data addresses; and replacing special tokens |
special tokens with code addresses. |
with code addresses or with pieces of machine code. |
|
|
If any complex computations involving addresses are performed, the |
If any complex computations involving addresses are performed, the |
results cannot be represented in the image file. Several applications that |
results cannot be represented in the image file. Several applications that |
Line 4467 startup.@footnote{In my opinion, though,
|
Line 4473 startup.@footnote{In my opinion, though,
|
using a doubly-linked list (whatever implementation).} |
using a doubly-linked list (whatever implementation).} |
|
|
@item |
@item |
|
The code addresses of run-time routines like @code{docol:} cannot be |
|
represented in the image file (because their tokens would be replaced by |
|
machine code in direct threaded implementations). As a workaround, |
|
compute these addresses at run-time with @code{>code-address} from the |
|
executions tokens of appropriate words (see the definitions of |
|
@code{docol:} and friends in @file{kernel.fs}). |
|
|
|
@item |
On many architectures addresses are represented in machine code in some |
On many architectures addresses are represented in machine code in some |
shifted or mangled form. You cannot put @code{CODE} words that contain |
shifted or mangled form. You cannot put @code{CODE} words that contain |
absolute addresses in this form in a relocatable image file. Workarounds |
absolute addresses in this form in a relocatable image file. Workarounds |
Line 4499 doc-savesystem
|
Line 4513 doc-savesystem
|
@cindex data-relocatable image files |
@cindex data-relocatable image files |
@cindex image files, data-relocatable |
@cindex image files, data-relocatable |
|
|
@cindex @file{gforth.fi}, relocatability |
|
These files contain relocatable data addresses, but fixed code addresses |
These files contain relocatable data addresses, but fixed code addresses |
(instead of tokens). They are specific to the executable (i.e., |
(instead of tokens). They are specific to the executable (i.e., |
@file{gforth} file) they were created with. E.g., the image |
@file{gforth} file) they were created with. For direct threading on some |
@code{gforth.fi} is a data-relocatable image file. |
architectures (e.g., the i386), data-relocatable images do not work. You |
|
get a data-relocatable image, if you use @file{gforth-makeimage} with a |
|
Gforth binary that is not doubly indirect threaded (@pxref{Fully |
|
Relocatable Image Files}). |
|
|
|
@node Fully Relocatable Image Files, Stack and Dictionary Sizes, Data-Relocatable Image Files, Image Files |
|
@section Fully Relocatable Image Files |
|
@cindex fully relocatable image files |
|
@cindex image files, fully relocatable |
|
|
|
@cindex @file{kern*.fi}, relocatability |
|
@cindex @file{gforth.fi}, relocatability |
|
These image files have relocatable data addresses, and tokens for code |
|
addresses. They can be used with different binaries (e.g., with and |
|
without debugging) on the same machine, and even across machines with |
|
the same data formats (byte order, cell size, floating point |
|
format). However, they are usually specific to the version of Gforth |
|
they were created with. The files @file{gforth.fi} and @file{kernl*.fi} |
|
are fully relocatable. |
|
|
|
There are two ways to create a fully relocatable image file: |
|
|
|
@menu |
|
* gforth-makeimage:: The normal way |
|
* cross.fs:: The hard way |
|
@end menu |
|
|
|
@node gforth-makeimage, cross.fs, Fully Relocatable Image Files, Fully Relocatable Image Files |
|
@subsection @file{gforth-makeimage} |
@cindex @file{comp-image.fs} |
@cindex @file{comp-image.fs} |
You can create a data-relocatable image file by creating two |
@cindex @file{gforth-makeimage} |
non-relocatable image files for different base addresses and processing |
|
them with @file{comp-image.fs}, which generates the relocation |
|
information by comparing the images. |
|
|
|
After loading @file{comp-image.fs}, you can invoke the word |
|
@code{comp-image}, which reads the names of the two input files and the |
|
name of the output file from the input stream. This program also |
|
produces some output on the standard output: It displays the offset |
|
(i.e., the difference between the base addresses of the images); |
|
moreover, for each cell that cannot be represented correctly in the |
|
image files, it displays a line like the following one: |
|
|
|
|
You will usually use @file{gforth-makeimage}. If you want to create an |
|
image @var{file} that contains everything you would load by invoking |
|
Gforth with @code{gforth @var{options}}, you simply say |
@example |
@example |
78DC BFFFFA50 BFFFFA40 |
gforth-makeimage @var{file} @var{options} |
@end example |
@end example |
|
|
This means that at offset $78dc from @code{forthstart}, one input image |
|
contains $bffffa50, and the other contains $bffffa40. Since these cells |
|
cannot be represented correctly in the output image, you should examine |
|
these places in the dictionary and verify that these cells are dead |
|
(i.e., not read before they are written). |
|
|
|
E.g., if you want to create an image @file{asm.fi} that has the file |
E.g., if you want to create an image @file{asm.fi} that has the file |
@file{asm.fs} loaded in addition to the usual stuff, you could do it |
@file{asm.fs} loaded in addition to the usual stuff, you could do it |
like this: |
like this: |
|
|
@example |
@example |
gforth --clear-dictionary asm.fs "savesystem asm.fi1 bye" |
gforth-makeimage asm.fi asm.fs |
gforth --clear-dictionary --offset-image asm.fs "savesystem asm.fi2 bye" |
|
gforth -m 100000 comp-image.fs -e "comp-image asm.fi1 asm.fi2 asm.fi bye" |
|
@end example |
@end example |
|
|
@cindex --clear-dictionary, creating image files |
@file{gforth-makeimage} works like this: It produces two non-relocatable |
@cindex --offset-image, creating image files |
images for different addresses and then compares them. Its output |
The flag @code{--clear-dictionary} ensures that the dictionary memory is |
reflects this: first you see the output (if any) of the two Gforth |
cleared at the start (so you won't see @code{comp-image} messages about |
invocations that produce the nonrelocatable image files, then you see |
spurious differences). The flag @code{--offset-image} loads the image at |
the output of the comparing program: It displays the offset used for |
a small offset from its normal position, ensuring that the resulting |
data addresses and the offset used for code addresses; |
nonrelocatable images have different bases (otherwise @code{comp-image} |
moreover, for each cell that cannot be represented correctly in the |
cannot work). |
image files, it displays a line like the following one: |
|
|
@node Fully Relocatable Image Files, Stack and Dictionary Sizes, Data-Relocatable Image Files, Image Files |
@example |
@section Fully Relocatable Image Files |
78DC BFFFFA50 BFFFFA40 |
@cindex fully relocatable image files |
@end example |
@cindex image files, fully relocatable |
|
|
|
@cindex @file{kern*.fi}, relocatability |
This means that at offset $78dc from @code{forthstart}, one input image |
These image files have relocatable data addresses, and tokens for code |
contains $bffffa50, and the other contains $bffffa40. Since these cells |
addresses. They are still a bit machine dependent with respect to the |
cannot be represented correctly in the output image, you should examine |
size and format (byte order, floating point format) of their data. The |
these places in the dictionary and verify that these cells are dead |
@file{kernlxxx.fi} files are fully relocatable. |
(i.e., not read before they are written). |
|
|
|
@cindex @code{savesystem} during @file{gforth-makeimage} |
|
@cindex @code{bye} during @file{gforth-makeimage} |
|
@cindex doubly indirect threaded code |
|
@cindex environment variable @code{GFORTHD} |
|
@cindex @code{GFORTHD} environment variable |
|
@cindex @code{gforth-ditc} |
|
There are a few wrinkles: After processing the passed @var{options}, the |
|
words @code{savesystem} and @code{bye} must be visible. A special doubly |
|
indirect threaded version of the @file{gforth} executable is used for |
|
creating the nonrelocatable images; you can pass the exact filename of |
|
this executable through the environment variable @code{GFORTHD} |
|
(default: @file{gforth-ditc}); if you pass a version that is not doubly |
|
indirect threaded, you will not get a fully relocatable image, but a |
|
data-relocatable image (because there is no code address offset). |
|
|
|
@node cross.fs, , gforth-makeimage, Fully Relocatable Image Files |
|
@subsection @file{cross.fs} |
|
@cindex @file{cross.fs} |
@cindex cross-compiler |
@cindex cross-compiler |
@cindex metacompiler |
@cindex metacompiler |
At present a fully relocatable image file can only be produced by |
|
@code{cross}, a batch compiler that accepts a Forth-like programming |
You can also use @code{cross}, a batch compiler that accepts a Forth-like |
language. This @code{cross} language has to be documented |
programming language. This @code{cross} language has to be documented |
yet. |
yet. |
|
|
@cindex target compiler |
@cindex target compiler |
@code{cross} not only allows the programmer to create fully relocatable |
@code{cross} also allows you to create image files for machines with |
image files, but also to create image files for machines with different |
different data sizes and data formats than the one used for generating |
data sizes and data formats than the one used for generating the image |
the image file. You can also use it to create an application image that |
file. This convenience is bought with restrictions and inconveniences in |
does not contain a Forth compiler. These features are bought with |
programming. E.g., addresses have to be stored in memory with special |
restrictions and inconveniences in programming. E.g., addresses have to |
words (@code{A!}, @code{A,}, etc.) in order to make the code |
be stored in memory with special words (@code{A!}, @code{A,}, etc.) in |
relocatable. |
order to make the code relocatable. |
|
|
|
|
@node Stack and Dictionary Sizes, Running Image Files, Fully Relocatable Image Files, Image Files |
@node Stack and Dictionary Sizes, Running Image Files, Fully Relocatable Image Files, Image Files |
@section Stack and Dictionary Sizes |
@section Stack and Dictionary Sizes |
Line 4583 relocatable.
|
Line 4625 relocatable.
|
|
|
If you invoke Gforth with a command line flag for the size |
If you invoke Gforth with a command line flag for the size |
(@pxref{Invoking Gforth}), the size you specify is stored in the |
(@pxref{Invoking Gforth}), the size you specify is stored in the |
dictionary. If you save the dictionary with @code{savesystem}, this size |
dictionary. If you save the dictionary with @code{savesystem} or create |
will become the default for the resulting image file. E.g., the |
an image with @file{gforth-makeimage}, this size will become the default |
following will create a non-relocatable version of gforth.fi with a 1MB |
for the resulting image file. E.g., the following will create a |
dictionary: |
fully relocatable version of gforth.fi with a 1MB dictionary: |
|
|
@example |
@example |
gforth -m 1M -e "savesystem gforth1M.fi bye" |
gforth-makeimage gforth.fi -m 1M |
@end example |
@end example |
|
|
In other words, if you want to set the default size for the dictionary |
In other words, if you want to set the default size for the dictionary |
and the stacks of an image, just invoke Gforth with the appropriate |
and the stacks of an image, just invoke @file{gforth-makeimage} with the |
options when creating the image. When creating a data-relocatable image, |
appropriate options when creating the image. |
you have to use the same size options for both @code{savesystem}s. |
|
|
|
@cindex stack size, cache-friendly |
@cindex stack size, cache-friendly |
Note: For cache-friendly behaviour (i.e., good performance), you should |
Note: For cache-friendly behaviour (i.e., good performance), you should |
Line 4620 gforth -i @var{image}
|
Line 4661 gforth -i @var{image}
|
@cindex executable image file |
@cindex executable image file |
@cindex image files, executable |
@cindex image files, executable |
If your operating system supports starting scripts with a line of the |
If your operating system supports starting scripts with a line of the |
form @code{#! ...}, you can make your image file executable, and you'll |
form @code{#! ...}, you just have to type the image file name to start |
just have to type the image file name to start Gforth with this image |
Gforth with this image file (note that the file extension @code{.fi} is |
file (note that the file extension @code{.fi} is just a convention). |
just a convention). I.e., to run Gforth with the image file @var{image}, |
|
you can just type @var{image} instead of @code{gforth -i @var{image}}. |
I.e., in most Unix systems, you just have to make the image file |
|
@var{image} executable with |
|
|
|
@example |
|
chmod +x @var{image} |
|
@end example |
|
|
|
and then you can invoke it by simply typing @var{image} instead of |
doc-#! |
@code{gforth -i @var{image}}. |
|
|
|
@node Modifying the Startup Sequence, , Running Image Files, Image Files |
@node Modifying the Startup Sequence, , Running Image Files, Image Files |
@section Modifying the Startup Sequence |
@section Modifying the Startup Sequence |
Line 4646 deferred word
|
Line 4680 deferred word
|
doc-'cold |
doc-'cold |
|
|
@code{'cold} is invoked just before the image-specific command line |
@code{'cold} is invoked just before the image-specific command line |
processing (by default, loading files and evaluating (@code{-e}) strings |
processing (by default, loading files and evaluating (@code{-e}) strings) |
starts. |
starts. |
|
|
A sequence for adding your initialization usually looks like this: |
A sequence for adding your initialization usually looks like this: |
Line 4664 You can make a turnkey image by letting
|
Line 4698 You can make a turnkey image by letting
|
(your turnkey application) that never returns; instead, it exits Gforth |
(your turnkey application) that never returns; instead, it exits Gforth |
via @code{bye} or @code{throw}. |
via @code{bye} or @code{throw}. |
|
|
|
@cindex command-line arguments, access |
|
@cindex arguments on the command line, access |
|
You can access the (image-specific) command-line arguments through the |
|
variables @code{argc} and @code{argv}. @code{arg} provides conventient |
|
access to @code{argv}. |
|
|
|
doc-argc |
|
doc-argv |
|
doc-arg |
|
|
|
If @code{'cold} exits normally, Gforth processes the command-line |
|
arguments as files to be loaded and strings to be evaluated. Therefore, |
|
@code{'cold} should remove the arguments it has used in this case. |
|
|
@c ****************************************************************** |
@c ****************************************************************** |
@node Engine, Bugs, Image Files, Top |
@node Engine, Bugs, Image Files, Top |
@chapter Engine |
@chapter Engine |
Line 4677 The ideas in this section have also been
|
Line 4725 The ideas in this section have also been
|
@cite{ANS fig/GNU/??? Forth} (in German) by Bernd Paysan, presented at |
@cite{ANS fig/GNU/??? Forth} (in German) by Bernd Paysan, presented at |
the Forth-Tagung '93 and @cite{A Portable Forth Engine} by M. Anton |
the Forth-Tagung '93 and @cite{A Portable Forth Engine} by M. Anton |
Ertl, presented at EuroForth '93; the latter is available at |
Ertl, presented at EuroForth '93; the latter is available at |
@*@file{http://www.complang.tuwien.ac.at/papers/ertl93.ps.Z}. |
@*@url{http://www.complang.tuwien.ac.at/papers/ertl93.ps.Z}. |
|
|
@menu |
@menu |
* Portability:: |
* Portability:: |
Line 5157 predictive value for the performance of
|
Line 5205 predictive value for the performance of
|
In @cite{Translating Forth to Efficient C} by M. Anton Ertl and Martin |
In @cite{Translating Forth to Efficient C} by M. Anton Ertl and Martin |
Maierhofer (presented at EuroForth '95), an indirect threaded version of |
Maierhofer (presented at EuroForth '95), an indirect threaded version of |
Gforth is compared with Win32Forth, NT Forth, PFE, and ThisForth; that |
Gforth is compared with Win32Forth, NT Forth, PFE, and ThisForth; that |
version of Gforth is 2\%@minus{}8\% slower on a 486 than the version |
version of Gforth is 2%@minus{}8% slower on a 486 than the direct |
used here. The paper available at |
threaded version used here. The paper available at |
@*@file{http://www.complang.tuwien.ac.at/papers/ertl&maierhofer95.ps.gz}; |
@*@url{http://www.complang.tuwien.ac.at/papers/ertl&maierhofer95.ps.gz}; |
it also contains numbers for some native code systems. You can find a |
it also contains numbers for some native code systems. You can find a |
newer version of these measurements at |
newer version of these measurements at |
@file{http://www.complang.tuwien.ac.at/forth/performance.html}. You can |
@url{http://www.complang.tuwien.ac.at/forth/performance.html}. You can |
find numbers for Gforth on various machines in @file{Benchres}. |
find numbers for Gforth on various machines in @file{Benchres}. |
|
|
@node Bugs, Origin, Engine, Top |
@node Bugs, Origin, Engine, Top |
Line 5172 find numbers for Gforth on various machi
|
Line 5220 find numbers for Gforth on various machi
|
Known bugs are described in the file BUGS in the Gforth distribution. |
Known bugs are described in the file BUGS in the Gforth distribution. |
|
|
If you find a bug, please send a bug report to |
If you find a bug, please send a bug report to |
@code{bug-gforth@@gnu.ai.mit.edu}. A bug report should |
@email{bug-gforth@@gnu.ai.mit.edu}. A bug report should |
describe the Gforth version used (it is announced at the start of an |
describe the Gforth version used (it is announced at the start of an |
interactive Gforth session), the machine and operating system (on Unix |
interactive Gforth session), the machine and operating system (on Unix |
systems you can use @code{uname -a} to produce this information), the |
systems you can use @code{uname -a} to produce this information), the |