Go to the first, previous, next, last section, table of contents.


Invoking Gforth

You will usually just say gforth. In many other cases the default Gforth image will be invoked like this:

gforth [files] [-e forth-code]

This interprets the contents of the files and the Forth code in the order they are given.

In general, the command line looks like this:

gforth [initialization options] [image-specific options]

The initialization options must come before the rest of the command line. They are:

--image-file file
-i file
Loads the Forth image file instead of the default `gforth.fi' (see section Image Files).
--path path
-p path
Uses path for searching the image file and Forth source code files instead of the default in the environment variable 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
Allocate size space for the Forth dictionary space instead of using the default specified in the image (typically 256K). The size specification consists of an integer and a unit (e.g., 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
Allocate size space for the data stack instead of using the default specified in the image (typically 16K).
--return-stack-size size
-r size
Allocate size space for the return stack instead of using the default specified in the image (typically 15K).
--fp-stack-size size
-f size
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.
--locals-stack-size size
-l size
Allocate size space for the locals stack instead of using the default specified in the image (typically 14.5K).
--help
-h
Print a message about the command-line options
--version
-v
Print version and exit
--debug
Print some information useful for debugging on startup.
--offset-image
Start the dictionary at a slightly different position than would be used otherwise (useful for creating data-relocatable images, see section Data-Relocatable Image Files).
--no-offset-im
Start the dictionary at the normal position.
--clear-dictionary
Initialize all bytes in the dictionary to 0 before loading the image (see section Data-Relocatable Image Files).
--die-on-signal
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.

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 several -es. 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. You may want to use the option --path, if your environment contains the variable GFORTHPATH.

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 first searched in `.', then in `~', then in the normal path (see above).


Go to the first, previous, next, last section, table of contents.