darwin-river / embed

An embeddable, tiny Forth interpreter with metacompiler.

embed: A tiny embeddable Forth interpreter

Project	Embed Forth VM and eForth Image
Author	Richard James Howe
Copyright	2017-2018 Richard James Howe
License	MIT
Email	[email protected]
Website	https://github.com/howerj/embed

This project contains a tiny 16-bit Virtual Machine (VM) optimized to execute Forth. It is powerful and well developed enough to be self hosted, the VM and Forth interpreter image can be used to recreate a new image from source (which is in embed.fth). embed.fth contains a more complete description of the Forth interpreter, the virtual machine (which is only ~400 Lines of C code) and how a Forth "meta-compiler" works.

The virtual machine is available as a library, as well, so it can be embedded into another project, hence the project name. The virtual machine (embed.c and embed.h), the eForth image (image.c), and the metacompiler (embed.fth) are all licensed under the MIT License.

Feel free to email me about any problems, or open up an issue on GitHub.

Program Operation

To build the project you will need a C compiler, and make. The system should build under Linux and Windows (MinGW). After installing make and a C99 compiler, simply type "make" to build the Forth virtual machine. An image containing a working Forth implementation is contained within image.c, which is built into the executable.

Linux/Unixen:

./embed

Windows:

embed.exe

To exit the virtual machine cleanly either type bye and then hit return, or press CTRL+D (on Linux) / CTRL+Z (on Windows) and then return.

The source code for image.c is provided in embed.fth, which contains an explanation on how a Forth cross compiler works (know as a metacompiler in Forth terminology) as well as a specification for the virtual machine and a little about Forth itself.

If you do not have a copy of make, but do have a C99 compiler, the following command should build the project:

cc -std=c99 main.c embed.c image.c util.c -o embed

Generating a new image is easy as well (using the built in image):

./embed -o new.blk embed.fth

We can then use the new image to generate a further image:

./embed -o new2.blk -i new.blk embed.fth

Ad infinitum, the two newly generated images should be byte for byte equal.

Unit tests can be ran typing:

make tests                     # Using make
./embed -o unit.blk t/unit.fth # manual invocation

Project Organization

• embed.c: The Embed Virtual Machine
• embed.h: The Embed Virtual Machine library interface
• main.c: Test driver for the Virtual Machine Library
• image.c: A Forth interpreter image, C code
• embed.fth: A meta compiler and a Forth interpreter
• unit.fth: Unit tests for the eForth image

Example Programs and Tests

Example programs and tests exist under the 't/' directory, these include test programs written in C that can extend the virtual machine with new functionality or change the input and out mechanisms to the virtual machine.

• call.c: Extends the virtual machine with floating point operations
• unix.c: Unix non-blocking and raw terminal I/O handling test
• win.c: Windows equivalent of unix.c.
• cpp.cpp: C++ test program to make sure library header is C++ compatible

Project Goals

The goal of the project is to create a VM which is tiny, embeddable, customizable through callbacks and most importantly self-hosting. It achieves all of these goals, but might fall short.

• Self-Hosting Metacompiler
• Man pages
• Document project
• Forth Unit tests
• C Unit tests, to test the library API
• C Test programs
  • Test applications for Windows/Unix non-block I/O, and callback extensions.
• Small standalone test programs
  • Cut down version of embed.fth
  • Bootloader
• Virtual Machine and eForth Image/Metacompiler that uses 'uintptr_t'
• Port the library to a small microcontroller (see https://github.com/howerj/arduino)