e4 is a standards-compliant embeddable Forth 2012 system. For more information, see the system label (doc/rst/core/stddoc/system-label.rst). For example usage, see the repl and examples directories.

Forth is an extremely powerful and yet extremely simple stack based programming language. The goal of e4 is to make Forth embeddable in the same way that SQLite has made SQL embeddable. e4 is reentrant safe, makes no dynamic allocations, and can run when initialized with as little as 2K of dynamic memory. e4 is written in ANSI C89 and will run on almost any target for which C code compiles, bare-metal or otherwise. The e4 kernel compiles and runs efficient threaded code that performs well enough for both embedded and general-purpose applications.

On top of all this, e4 is distributed as single header/single source-file amalgamation, so it is easy to incorporate into existing projects, and this source file is structured in such a way that C preprocessor definitions can be used to include or exclude builtin wordlists, making e4 even more flexible and compact.

The e4 documentation is currently a work in progress, as is e4 itself, and as such e4 should not be considered "production ready" (unless you're feeling extremely adventurous), but despite this you may still find it useful. e4 can be used to spin up an interactive debug environment on a resource constrained embedded environment in a matter of minutes (see examples/arduino) and it is trivial to write Forth words to allow for C functions to be called in an interactive environment. On a POSIX system, the e4 REPL is even more powerful and supports loading dynamic libraries and calling arbitrary functions via libffi (see examples/chip8).

The ultimate goal of e4 is to provide a truly minimal, modular, and portable standards compliant Forth implementation. If you have any suggestions that may help to make this goal a reality, or any questions or comments about where the project is at currently, please do not hesitate to reach out.

e4 is an Embeddable 4th, so e4 can be taken as an abbreviation for that. Also, e4 is a nice convenient two letter name that doesn't seem to be in use by any major software project currently. Also, 1. e4 is the first move in several of my favorite chess openings.

Generating the amalgamated source file, and by extension building the REPL, requires amal.rb (which itself requires Ruby). Additionally, the REPL requires libedit and the REPL and unit tests both require libffi for FFI support. If FFI support is not desired/needed for the REPL, the unit tests, or both, then these applications may be built without libffi by invoking make with the environment variable(s) E4__REPL_OMIT_FFI, E4__TESTS_OMIT_FFI, and/or E4__OMIT_FFI set to any non-empty value as appropriate. The build tests unconditionally require the presence of libffi in order to pass for build configurations that require libffi, however they should pass for all other configurations whether libffi is present or not.

To generate the amalgamated source file or to build the REPL and/or tests using the provided Makefile, a C compiler that recognizes flags like -MMD and -MP for generating object dependencies is necessary. GCC and Clang are both capable of this and the provided Makefile has been verified to work correctly with either. If, for some reason, you do not have access to either of those compilers but wish to generate a bespoke e4 amalgamation, please refer to the Makefile for an example of how amal.rb should be invoked.

The amalgamated source file generated by amal.rb (and made available via official releases) has no dependencies beyond a C compiler supporting the ISO C90 (aka ANSI C89) standard.

Finally, HTML, LaTeX, and PDF documentation can be generated using the doc-html, doc-latex, and doc-pdf rules respectively. These rules all require Sphinx and doc-pdf requires pdfTeX, in particular the dvips and latexmk applications. On many Linux distributions, these applications are available either as individual packages or in some kind of "texlive-core" (or similarly named) package. In furthermore, additional style files (capt-of.sty, fncychap.sty, framed.sty, needspace.sty, tabulary.sty, upquote.sty, and wrapfig.sty) are required by the LaTeX files generated by Sphinx. On many Linux distributions, these additional style files are available in some kind of "texlive-latexextra" (or similarly named) package.

Alternatively, it is possible to browse the raw RST documentation files in the doc directory with any text editor or RST viewer.

Unless otherwise noted, all source in this directory tree is copyright 2022 Shawn M. Chapla and is released under the MIT license. For more details, please see the LICENSE file.

Where noted, some of the division implementations used by e4 are based upon the reference implementations in Hank Warren's "Hacker's Delight" 2nd Edition. This code was obtained in digital form from Henry Warren's Hacker's Delight website and is adapted here with Warren's generous permission to "use, copy, and distribute any of the code on [the Hacker's Delight] web site, whether modified by you or not," with or without attribution. I strongly recommend that anyone considering purchasing this book do so. It is a true classic.