Reva Forth
From RevaWiki
Contents |
About Reva Forth
What is Reva?
From the file doc/reva.txt in the distribution:
There are plenty of full-featured Forth compilers: IsForth, BigForth, Win32forth, Gforth, and many commercial Forths. Reva is based on RetroForth, which is modeled after CMforth, Colorforth, Eforth and Pygmy. It uses some, but not all, of Chuck Moore's newer ideas. It is currently targeted at the Intel x86 CPU family, and runs natively on Windows and Linux. More information on Reva is available in the Reva Q&A. The contents of the Reva library, in the lib directory are detailed here. The word list changes from release to release, and is documented here.
Reva is...
- Tiny: binaries are about 15k for both Windows and Linux
- Fast: all the core functions are written in assembly-language
- Cross-platform: Almost all words are available for both Windows and Linux.
- Public domain: You are free to modify it for your own use. I would appreciate it if you credited Reva as the source, however.
- Documented: The Q&A document mentioned above is only one of several documents distributed with Reva. There is also the word list which documents all core words, as well as the tutorial, which steps you through some lessons. Besides these, there are several example programs, as well as the complete source code.
- Practical: designed to accomplish real-world goals quickly and easily.
... but is not:
- ANS compliant: There are loads of ANS-compliant Forths. This is not one of them, though there is an attempt at a compatibility layer. If you wish, you can start Reva with the -a command-line switch -- this will load the ANS compatibility layer (which is incomplete).
- Complete: There is no attempt to add every possible feature. Rather, the idea is that it should be possible to build whatever is required from the core set, in a simple manner.
How can I get and build it?
The latest version is available from the [Reva website]. All the sources are included for both Windows and Linux, but you cannot build the Linux build on Windows due to a technical problem.
Reva is built using FASM, and now requires FASM 1.62 or later - earlier versions will not build Reva. I'm providing a ZIP file with Linux and Windows FASM 1.62 here. The Linux version also requires gcc . If you don't want to build it yourself, you can use the binaries provided in the "bin" subdirectory of the distribution. Otherwise, if you have the tools listed above, just type make from a command-shell in the top directory of the distribution and in a few seconds, you will have built Reva. I use GNU make, and I've heard the Makefile doesn't work with all versions of make.
Reva is built in two stages: first, "revacore" is built. Revacore is a stripped-down all-assembly core containing the interpreter,compiler and about 100 words. It is then used to create "reva". Revacore knows that if there is something on its command-line, it should be interpreted as a file to read in. So the "reva" build process is something like "revacore reva.f".
Sources
The assembly language sources are few: revacore.asm (the main part of revacore), corewin.asm (for Windows), corelin.asm (for Linux) and brieflz.asm for the compression code.
The rest of the source is all high-level Forth (well, a great deal of the words are implemented in inline assembler which is basically impossible to read unless you are an opcode-geek). The main file is 'reva.f', which includes all the other files. If you wish to make a stripped-down version of Reva, you can start by commenting-out lines in reva.f.
If you wish to build a custom program, where your code was incorporated into the executable just as 'reva.f' is, you may do so very easily. Simply enter whatever code you want, and do "save myfile" to create a new executable "myfile". You will probably want to look at what 'reva.f' does, and do something similar yourself so your startup code is executed.
Register usage
Register use is similar to that of RetroForth and ColorForth. It's designed to be as free and easy to work with as possible. Here's what you need to know:
Register Useage EAX Top of stack ESI Data stack [ESI] Second item on stack ESP Return stack
Basically these are the only registers you need to be concerned about saving.
Windows system calls save ESI and return values in EAX, which is mostly what we want, so there is no need to be too concerned here. Linux calls are supposed to save ESI, but registers to syscalls are sometimes passed in ESI.
Dictionary structure
The dictionary is a simple linked list; this is the basic format of each entry:
dd word_class
current_entry:
dd link_to_previous_entry
dd address_of_code
db length_of_name
db 'name_of_word'
The 'address_of_code' points to the "xt", that is the executable code for the word. Each word is layed out like this (as of 6.0.3):
jmp xt ; four-byte signature, $cc900eeb nop int3 dd 0 ; reserved dd size_of_word dd pointer_to_dictionary ; "current_entry" above xt: ...
Miscellaneous
Reva allows you to make use of several numeric bases by prefixing the number with a symbol. The symbols are listed below, along with examples:
Symbol Meaning Example # Decimal #129 $ Hexadecimal $A000 % Binary %10011001 & Octal &177 ' ASCII 'A
This allows you to use the best base for each word without changing the base variable.
Example code
In the 'examples' directory there are a number of sample programs, including Windows and Linux specific ones. You should look at them to see how things are done. A few of the files are:
- hello.f - Just how simple can "Hello, world!" be?
- catch.f - Shows how to use the catch and throw mechanism.
- gtk.f - Shows how to interface with the GTK library on Linux
- winhello.f - Very simply shows how to interface with Windows and display a message-box.
- winapp.f - More complete windows example, showing how to make a Windows callback function.
- numberparse.f - Example of how to hook the parser and allow Reva to accept numbers with commas, like 1,234,567
There are other examples there as well, it's a good idea to take a look and see how things are done.
