To add words to the core dictionary the word implementation must be converted into its compiled form, either native assembler for CODEWORDS or a sequence of words representing the body of a COLON word (called ITC assembler or just ITC). The words in core/words are examples of ITC assembler words and words in arm/words or rv/words are examples of native assembler words.

Writing ITC assembler by hand is cumbersome. Transpiling provides a way to convert word source in Forth into its ITC equivalent. The tooling for transpiling is split between amforth itself and amforth-shell. When transpiling is enabled (tpile+/tpile-) amforth emits tokens during compilation of a word back to the host. These tokens are relatively easy to convert to ITC assembler source, this is what amforth-shell does. Here’s an example of the transpiling interaction between amforth and amforth-shell compiling word fib followed by the transpiled result emitted by amshell.

|S|    2|: fib 
|O|    2|WW666962 X400428D4 X40000681
|S|    3|    dup 2 > if 
|O|    3|X400002D4 X40001E98 X400007BC X400011C0 X00000000 F400428E8
|S|    4|       dup 1- recurse swap 1- 1- recurse + exit 
|O|    4|X400002D4 X40000E64 X400428D4 X400000D4 X40000E64 X40000E64 X400428D4 X40000128 X400002A4
|S|    5|    then 
|O|    5|L400428E8
|S|    6|    drop 1 
|O|    6|X40000098 X40001E84
|S|    7|;
|O|    7|X40000288 END

# : fib
COLON "fib", FIB
    # dup 2 > if
    .word XT_DUP, XT_TWO, XT_GREATER, XT_DOCONDBRANCH, 1f
       # dup 1- recurse swap 1- 1- recurse + exit
       .word XT_DUP, XT_1MINUS, XT_FIB, XT_SWAP, XT_1MINUS, XT_1MINUS, XT_FIB, XT_PLUS, XT_FINISH
    # then
1:     # drop 1
    .word XT_DROP, XT_ONE
   # ;
   .word XT_EXIT
END FIB

To trigger transpiling, use the #transpile directive (instead of #include directive) to load a Forth source file. Amforth-shell will attempt to transpile all word definitions in the file. If the words compile successfully the transpiled ITC should also be correct. Note however that the words being transpiled can only use core words or words previously transpiled in the same amforth-shell session (e.g. words preceding in the same file). Recursive calls should also transpile correctly. It is therefore important to review the transpiled results for correctness.

Amforth-shell must have an up to date symbol table matching the compiled amforth binary. This is needed to translate raw addresses to the corresponding XT symbols. The symbol table is normally included as file named amforth.sym and should be located in the current working directory. Option --sym-file allows pointing amforth-shell at a different file instead.

Amforth-shell emits the ITC along with the original Forth line (as a comment). It follows the offsets of the original source lines to offset the ITC code. It collects the continuous block of comments before the word and emits it as a long description block comment after the ITC word header. Similarly it parses the line that starts the word definition to look for stack signature and following short description to emit with the ITC header (to be used in the reference card tables).

The transpiler support can be compiled in or out of amforth with WANT_TRANSPILER config option. Amforth-shell will report an error if #transpile is used without transpiler being available on the target.