You will usually use gforthmi. If you want to create an
image file that contains everything you would load by invoking
Gforth with gforth args, you simply say:
gforthmi file args
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, which looks similar to this:
code offset=-32541536048 xt offset=-32541536080 label offset=-32541536112 section start size dp 0 $7F3680DFE040 $800000 $22EB20 1 $7F368F285000 $5000 $318 ... section start size dp 0 $7FEF133FF200 $800000 $22EB20 1 $7FEF21765000 $5000 $318 ... compare warnings (add section start to offset): Compare section 0 A9800 7F368F27849A 7FEF2175849A 154E58 FFFFFFFFFF99CB10 FFFFFFFFFFBA3B10 ... stats: addr=1378F code=838E xts=12FA labels=24D errs=22 Compare section 1 stats: addr=3C code=0 xts=7 labels=0 errs=0 ... end warnings
First the various offsets for code addresses and xts (for generating
tokens) are given, then information about the sections (relevant for
data addresses); the start address of corresponding sections should be
different (that is used for finding out what data is an address and
what is not), size and dp (where here points to when in this
section) for the corresponding sections should be the same.
Next, warnings resulting from comparing data addresses are shown: E.g.,
Compare section 0 A9800 7F368F27849A 7FEF2175849A
tells that at offset $A9800 in section 0, in one image file the
data is $7F368F27849A, while in the other it is
$7FEF2175849A.
The cells mentioned in the warnings cannot be represented correctly in the output image and result in unintended values after loading, so you should examine these places in the dictionary and verify that these cells are dead (i.e., not read before they are written).
One way to suppress these warnings is to zero these cells at the end of whatever code is performed by args in the command line above. Of course, you should be certain that the overwritten data is dead.
A frequent reason for such warnings is that an allocated
address is stored somewhere in the dictionary. In some cases you may
want to preserve the data in allocated memory in an image. You can
use save-mem-dict for that.
There is a deferred word (see Deferred Words) that is called
before saving an image: 'image. You can plug your own actions
into this word, but make sure you call the action that was there
before, too (e.g., with defers).
deferred word executed before saving an image
You may want to reorganize the data from the in-image form back to the
run-time form when starting up from the image. Plug your startup
actions into 'cold (see Modifying the Startup Sequence).
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). The normal gforth
executable is used for comparing the non-relocatable images and
creating the relocatable image; you can pass the exact filename of
this executable through the environment variable GFORTH.