Gforth is made up of two parts; an executable “engine” (named
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
gforth-fast, which is faster, but gives less
informative error messages (see Error messages) and may catch some
errors (in particular, stack underflows and integer division errors)
later or not at all. You should use it for debugged,
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:
Loads the Forth image file instead of the default gforth.fi (see Image Files).
Loads the image file and leaves all further command-line arguments
to the image (instead of processing them as engine options). This is
useful for building executable application images on Unix, built with
gforthmi --application ....
Uses path for searching the image file and Forth source code files
instead of the default in the environment variable
the path specified at installation time and the working directory
. (e.g., /usr/local/share/gforth/0.2.0:.). A path is given
as a list of directories, separated by ‘:’ (previous versions had
‘;’ for other OSes, but since Cygwin now only accepts
/cygdrive/<letter>, and we dropped support for OS/2 and MS-DOS,
it is ‘:’ everywhere).
Allocate size space for the Forth dictionary space instead of
using the default specified in the image (typically 256K). The
size specification for this and subsequent options consists of
an integer and a unit (e.g.,
4M). The unit can be one of
size, in this case Cells),
G (Gigabytes), and
T (Terabytes). If no unit is specified,
e is used.
Allocate size space for the data stack instead of using the default specified in the image (typically 16K).
Allocate size space for the return stack instead of using the default specified in the image (typically 15K).
Allocate size space for the floating point stack instead of
using the default specified in the image (typically 15.5K). In this case
the unit specifier
e refers to floating point numbers.
Allocate size space for the locals stack instead of using the default specified in the image (typically 14.5K).
Normally, Gforth tries to start up even if there is not enough virtual
memory for the dictionary and the stacks (using
on OSs that support it); so you can ask for a really big dictionary
and/or stacks, and as long as you don’t use more virtual memory than
is available, everything will be fine (but if you use more, processes
get killed). With this option you just use the default allocation
policy of the OS; for OSs that don’t overcommit (e.g., Solaris), this
means that you cannot and should not ask for as big dictionary and
stacks, but once Gforth successfully starts up, out-of-memory won’t
Print a message about the command-line options
Print version and exit
Print some information useful for debugging on startup.
Start the dictionary at a slightly different position than would be used otherwise (useful for creating data-relocatable images, see Data-Relocatable Image Files).
Start the dictionary at the normal position.
Initialize all bytes in the dictionary to 0 before loading the image (see Data-Relocatable Image Files).
Normally Gforth handles most signals (e.g., the user interrupt SIGINT,
or the segmentation violation SIGSEGV) by translating it into a Forth
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.
Disable or enable dynamic superinstructions with replication (see Dynamic Superinstructions).
Disable dynamic superinstructions, use just dynamic replication; this is useful if you want to patch threaded code (see Dynamic Superinstructions).
Use only the first N static superinstructions compiled into the
engine (default: use them all; note that only
any). This option is useful for measuring the performance impact of
Use specified metric for determining the cost of a primitive or static
superinstruction for static superinstruction selection.
is the native code size of the primive or static superinstruction,
ls is the number of loads and stores,
lsu is the number of
loads, stores, and updates, and
nexts is the number of dispatches
(not taking dynamic superinstructions into account), i.e. every
primitive or static superinstruction has cost 1. Default:
codesize if you use dynamic code generation, otherwise
This option is useful for measuring the performance impact of static superinstructions. By default, an optimal shortest-path algorithm is used for selecting static superinstructions. With --ss-greedy this algorithm is modified to assume that anything after the static superinstruction currently under consideration is not combined into static superinstructions. With --ss-min-nexts this produces the same result as a greedy algorithm that always selects the longest superinstruction available at the moment. E.g., if there are superinstructions AB and BCD, then for the sequence A B C D the optimal algorithm will select A BCD and the greedy algorithm will select AB C D.
Prints some metrics used during static superinstruction selection:
code size is the actual size of the dynamically generated code.
Metric codesize is the sum of the codesize metrics as seen by
static superinstruction selection; there is a difference from
size, because not all primitives and static superinstructions are
compiled into dynamically generated code, and because of markers. The
other metrics correspond to the ss-min-... options. This
option is useful for evaluating the effects of the --ss-...
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)
-e bye to the command line. You can also process the
command-line arguments with a Forth program (see OS command line arguments).
If you have several versions of Gforth installed,
invoke the version that was installed last.
invokes a specific version. If your environment contains the variable
GFORTHPATH, you may want to override it by using the
On startup, before processing any of the image option, the user
initialization file either specified in the environment variable
GFORTH_ENV or, if not set, ~/.config/gforthrc0 is included, if
it exists. If
GFORTH_ENV is “
off,” nothing is
included. After processing all the image options and just before
printing the boot message, the user initialization file
~/.config/gforthrc from your home directory is included, unless the
--no-rc is given.