How to do a translation

Last updated November 27, 2002.

Here we describe the stages of ^Forth to C translation, with the traditional Gforth benchmark code as an example, from preparation of the source to running the compiled translation.

The first step is to rewrite the Forth source in the ^Forth dialect. The environment in which Forth to C translation takes place is not unlike that in Forth cross compilation, which means there can be issues of scope, as described by Elizabeth Rather. Using a dialect can help control that.
It's actually pretty easy to rewrite to ^Forth. The ^Forth Words document provides some guidance, but actual examples of rewritten code like those in gfbench.hf are probably more instructive.
Next is to translate the ^Forth source to C source. For example, to translate gfbench.hf to gfbench-ext.c and gfbench-dll.c, start in a directory containing gfbench.hf, plus the files listed under ^Forth translator for pfe. (The file hffloat.hf isn't actually needed here, but it's part of the ^Forth system.) Then run the script dohftrans like this:
```
    ./dohftrans gfbench
```
That should produce the two C source files.
Next, compile the C files into a pfe shared library module, which would be called gfbench.so on several systems. How to do this and the available register options depend on the host system; and we have tested it only for the three systems for which scripts are provided in the directories under scripts for building single pfe modules.
For darwin/ppc, all the possibilities for generating or not generating code that keeps the top of the data and floating point stacks cached in registers, i.e., TOS and FTOS, are available. For linux/ia32, a TOS register is not available, and we have not succeeded in implementing an FTOS register. For hpux/hppa, the system we had available worked only with TOS and FTOS in registers, and we still haven't digested that!
Finally, run the compiled code under pfe. ^Forth has a word MAKE-INDEX that makes Forth words defined in the translation available for interpretation in the dictionary, once the code is loaded as a module by pfe. For example, after starting pfe, the sequence
```
    loadm gfbench
    .primes
```
should produce a display of the prime numbers calculated by the Eratosthenes sieve benchmark. The script dogfbench runs and times all the benchmarks.

There is also a floating point example, Krishna Myneni's semiconductor laser rate benchmark, rewritten for ^Forth in slbench.hf. It has a slightly more complex dependence on external modules, and its calling sequence in the doslbench script reflects that.