Node:Invoking Gforth, Next:Leaving Gforth, Previous:Gforth Environment, Up:Gforth Environment
Gforth is made up of two parts; an executable "engine" (named
gforth
or gforth-fast
) and an image file. To start it, you
will usually just say gforth
- this automatically loads the
default image file gforth.fi
. In many other cases the default
Gforth image will be invoked like this:
gforth [file | -e forth-code] ...
This interprets the contents of the files and the Forth code in the order they are given.
In addition to the gforth
engine, there is also an engine
called gforth-fast
, which is faster, but gives less
informative error messages (see Error messages) and may catch some
stack underflows later or not at all. You should use it for debugged,
performance-critical programs.
Moreover, there is an engine called gforth-itc
, which is
useful in some backwards-compatibility situations (see Direct or Indirect Threaded?).
In general, the command line looks like this:
gforth[-fast] [engine options] [image options]
The engine options must come before the rest of the command line. They are:
--image-file file
-i file
gforth.fi
(see Image Files).
--appl-image file
gforthmi --application ...
.
--path path
-p path
GFORTHPATH
or
the path specified at installation time (e.g.,
/usr/local/share/gforth/0.2.0:.
). A path is given as a list of
directories, separated by :
(on Unix) or ;
(on other OSs).
--dictionary-size size
-m size
4M
). The unit can be one of b
(bytes), e
(element
size, in this case Cells), k
(kilobytes), M
(Megabytes),
G
(Gigabytes), and T
(Terabytes). If no unit is specified,
e
is used.
--data-stack-size size
-d size
--return-stack-size size
-r size
--fp-stack-size size
-f size
e
refers to floating point numbers.
--locals-stack-size size
-l size
--help
-h
--version
-v
--debug
--offset-image
--no-offset-im
--clear-dictionary
--die-on-signal
THROW
. With this option, Gforth exits if it receives such a
signal. This option is useful when the engine and/or the image might be
severely broken (such that it causes another signal before recovering
from the first); this option avoids endless loops in such cases.
--no-dynamic
--dynamic
--no-super
As explained above, the image-specific command-line arguments for the
default image gforth.fi
consist of a sequence of filenames and
-e forth-code
options that are interpreted in the sequence
in which they are given. The -e forth-code
or
--evaluate forth-code
option evaluates the Forth
code. This option takes only one argument; if you want to evaluate more
Forth words, you have to quote them or use -e
several times. To exit
after processing the command line (instead of entering interactive mode)
append -e bye
to the command line.
If you have several versions of Gforth installed, gforth
will
invoke the version that was installed last. gforth-version
invokes a specific version. If your environment contains the variable
GFORTHPATH
, you may want to override it by using the
--path
option.
Not yet implemented:
On startup the system first executes the system initialization file
(unless the option --no-init-file
is given; note that the system
resulting from using this option may not be ANS Forth conformant). Then
the user initialization file .gforth.fs
is executed, unless the
option --no-rc
is given; this file is searched for in .
,
then in ~
, then in the normal path (see above).