Invoking Gforth (Gforth Manual)

Next: Leaving Gforth, Previous: Gforth Environment, Up: Gforth Environment [Contents][Index]

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

--image-file file ¶
-i file: Loads the Forth image file instead of the default gforth.fi (see 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 ....
--no-0rc ¶: Do not load ~/.config/gforthrc0 nor the file specified by GFORTH_ENV.
--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 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).
--dictionary-size size ¶
-m size: Allocate size space for the Forth dictionary space instead of using the default specified in the image (default: 8M). The size specification for this and subsequent options consists of an integer and a unit (e.g., 1G). 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 (default: 16K).
--return-stack-size size ¶
-r size: Allocate size space for the return stack instead of using the default specified in the image (default: 15K).
--fp-stack-size size ¶
-f size: Allocate size space for the floating point stack instead of using the default specified in the image (default: 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 (default: 14.5K).
--map_32bit ¶: Allocate the dictionary and some other areas in the lower 2GB of the address space, if possible. The purpose of this option is debugging convenience.
--vm-commit ¶: Normally, Gforth tries to start up even if there is not enough virtual memory for the dictionary and the stacks (using MAP_NORESERVE 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 kill it.
--help ¶
-h: Print a message about the command-line options
--version ¶
-v: Print version and exit
--diag ¶
-D: Checks for and reports some performance problems.
--debug ¶: Print some information useful for debugging on startup.
--debug-mcheck ¶: Try to find and report erroneous usage of allocate, free, and the C functions malloc(), free(), etc.
--offset-image ¶: Start the dictionary at a slightly different position than would be used otherwise (useful for creating data-relocatable images, see 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 Data-Relocatable Image Files).
--die-on-signal [number] ¶: 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. The optional number set the number of signals to be handled; only the last one will cause Gforth to exit.
--ignore-async-signals ¶: Ignore asynchronous signals (e.g., SIGINT generated with Ctrl-c).

Code generation options

2.1.1 Code generation options ¶

--no-dynamic ¶

--dynamic

Disable or enable dynamic superinstructions with replication (see Dynamic Superinstructions). Default enabled.

--no-dynamic-image ¶

Disable dynamic native-code generation when loading the Gforth image, but generate dynamic native code afterwards. This option is useful when debugging Gforth’s code generator.

--no-super ¶

Disable dynamic superinstructions, use just dynamic replication; this is useful if you want to patch threaded code (see Dynamic Superinstructions).

--ss-number=N ¶

Use only the first N static superinstructions compiled into the engine (default: use them all; note that only gforth-fast has any). This option is useful for measuring the performance impact of static superinstructions.

--ss-min-codesize ¶

--ss-min-ls

--ss-min-lsu

--ss-min-nexts

Use specified metric for determining the cost of a primitive or static superinstruction for static superinstruction selection. Codesize 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 nexts.

--ss-greedy ¶

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.

--opt-ip-updates=n ¶

Set the level of IP-update optimization (default: 31 (7+3*8)). n is computed as n1+8*n2.

n1 indicates the use of IP-update optimization in straight-line code: 0 means no IP-update optimization, 1 combines IP-update optimizations of primitives without inline arguments, 2 also eliminates the dead IP updates of ;s, execute-;s and fast-throw, >2 eliminates the IP updates in front of several frequently-used primitives with inline arguments.

n2 is the number of ip-updates that can replace a load in a backwards or unconditional branch; for conditional forward branches only n2/2 ip-updates replace a load (to avoid too many additional updates in the fall-through path).

--code-block-size=size ¶

Size of native-code blocks (default: 2M). Gforth allocates as many blocks of this size as necessary.

--print-metrics ¶

On exit from Gforth: Print 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 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.

--print-prims ¶

When exiting GforthL: Print the primitives with static usage counts. E.g., one line might look like:

?branch           1-1  0   21 1575   73 0x5573e4048c33 len= 4+ 25+ 3 send=0

The colums are, from left to right: name of the primitive, stack-caching state transition (from a state with 1 stack item in a register to the same state in the example), IP offset for this version of the primitive (0 for most primitives, but, e.g., for ?branch there are also versions with 0-zero offset), index of the primitive, index of the corresponding branch-to-IP variant (in case of a branch), static number of occurences of the primitive in the loaded/compiled code, address of the code of the primitive (or (nil) if the primitive is not relocatable), length of the parts of this code: ip-update+main+dispatch, and whether the primitive ends a superblock (i.e., an unconditional branch or the like).

--print-nonreloc ¶

When starting Gforth: Print the non-relocatable primitives.

--print-sequences ¶

When loading the image: For each superblock in the image, print the sequence of primitives.

--tpa-noautomaton ¶

--tpa-noequiv

These options are about using an automaton for speeding up startup and compilation, in particular the shortest-path algorithm used for selecting static superinstructions and stack caching variants; tpa stands for for “tree-parsing automaton” (although we only have sequences, not trees). In the gforth engine the default is to use an automaton with state equivalence (state equivalence reduces the number of states compared to having one state for every sequence prefix), which is the fastest option and requires the least memory.

With static superinstructions the automaton does not work correctly, so Gforth falls back to --tpa-noautomaton in that case unless you ask for --tpa-noequiv (gforth-fast uses static superinstructions and therefore --tpa-noautomaton by default).

--tpa-noequiv turns off state equivalence, which costs memory and compiles a little slower than using an automaton.

--tpa-noautomaton turns off using the automaton. This consumes quite a bit more compile time, and should in theory use less memory than using an automaton, but apparently there is a bug in Gforth, and it consumes more memory.

The following shows the startup speed and memory consumption of Gforth 0.7.9_20240821 run with gforth-fast -e bye (plus the options given in the table) on a Core-i5 6600K (Skylake):

 cycles    instructions KB(RSS) other options
23_309_239  43_534_167   9228   --ss-number=0
26_399_456  51_895_687  11316   --ss-number=0 --tpa-noequiv
40_427_672  93_709_354  10988   --ss-number=0 --tpa-noautomaton
27_599_969  53_126_621  11320
27_732_944  53_128_381  11320   --tpa-noequiv
42_960_520  95_466_840  11044   --tpa-noautomaton

--tpa-trace ¶

This option produces data about the number of states generated during startup and compilation.

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

On startup, before processing any of the image option, the user initialization file is included, if it exists. The user initialization file is ~/.config/gforthrc0, or, if the environment variable GFORTH_ENV is set, it contains the name of the user initialization file. You can suppress loading this file with by setting GFORTH_ENV to off, or with the option --no-0rc.

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 option --no-rc is given.

Warning levels can be set with

-W ¶: Turn off warnings
-Won ¶: Turn on warnings (level 1)
-Wall ¶: Turn on beginner warnings (level 2)
-Wpedantic ¶: Turn on pedantic warnings (level 3)
-Werror ¶: Turn warnings into errors (level 4)