www.delorie.com/gnu/docs/gforth/gforth_6.html

search

	Buy GNU books!

Gforth Manual

2.1 Invoking Gforth

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 section 6. Error messages). You should use it for debugged, performance-critical programs.

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

Loads the Forth image file instead of the default `gforth.fi' (see section 13. Image Files).

--appl-image file

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 ....

--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 for this and subsequent options 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 13.4 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 13.4 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 -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).