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 errors (in particular, stack underflows and integer division errors) 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:
gforthmi --application ....
GFORTHPATHor 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).
4M). The unit can be one of
e(element size, in this case Cells),
T(Terabytes). If no unit is specified,
erefers to floating point numbers.
MAP_NORESERVEon 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 kill it.
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.
gforth-fasthas any). This option is useful for measuring the performance impact of static superinstructions.
Codesizeis the native code size of the primive or static superinstruction,
lsis the number of loads and stores,
lsuis the number of loads, stores, and updates, and
nextsis the number of dispatches (not taking dynamic superinstructions into account), i.e. every primitive or static superinstruction has cost 1. Default:
codesizeif you use dynamic code generation, otherwise
code sizeis the actual size of the dynamically generated code.
Metric codesizeis the sum of the codesize metrics as seen by static superinstruction selection; there is a difference from
code 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-... options.
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
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
--no-rc is given; this file is searched for in .,
then in ~, then in the normal path (see above).