You will usually use gforthmi. If you want to create an
image file that contains everything you would load by invoking
Gforth with gforth options, you simply say:
gforthmi file options
E.g., if you want to create an image asm.fi that has the file asm.fs loaded in addition to the usual stuff, you could do it like this:
gforthmi asm.fi asm.fs
gforthmi is implemented as a sh script and works like this: It produces two non-relocatable images for different addresses and then compares them. Its output reflects this: first you see the output (if any) of the two Gforth invocations that produce the non-relocatable image files, then you see the output of the comparing program: It displays the offset used for data addresses and the offset used for code addresses; moreover, for each cell that cannot be represented correctly in the image files, it displays a line like this:
78DC BFFFFA50 BFFFFA40
This means that at offset $78dc from forthstart, one input image
contains $bffffa50, and the other contains $bffffa40. Since these cells
cannot be represented correctly in the output image, you should examine
these places in the dictionary and verify that these cells are dead
(i.e., not read before they are written).
If you insert the option --application in front of the image file
name, you will get an image that uses the --appl-image option
instead of the --image-file option (see Invoking Gforth). When you execute such an image on Unix (by typing the image
name as command), the Gforth engine will pass all options to the image
instead of trying to interpret them as engine options.
If you type gforthmi with no arguments, it prints some usage instructions.
There are a few wrinkles: After processing the passed options, the
words savesystem and bye must be visible. A special
doubly indirect threaded version of the gforth executable is
used for creating the non-relocatable images; you can pass the exact
filename of this executable through the environment variable
GFORTHD (default: gforth-ditc); if you pass a version
that is not doubly indirect threaded, you will not get a fully
relocatable image, but a data-relocatable image
(see Data-Relocatable Image Files), because there is no code
address offset). The normal gforth executable is used for
creating the relocatable image; you can pass the exact filename of
this executable through the environment variable GFORTH.