nasmjf - a NASM port of JONESFORTH

MOVED! Hello, I am moving my repos to http://ratfactor.com/repos/ and setting them to read-only ("archived") on GitHub. Thank you, -Dave

This is a fully-functioning Forth interpreter faithfully ported from the original by Richard W.M. Jones:

https://rwmj.wordpress.com/2010/08/07/jonesforth-git-repository/

You can see the full original source in the jonesforth/ directory in this repo.

Assemble and run nasmjf like so:

$ ./build.sh
$ ./nasmjf
JONESFORTH VERSION 1
20643 CELLS REMAINING
OK
: hello ." Hello world!" CR ;
hello
Hello world!
BYE
$

This repo is a port from the original GNU Assembler (GAS) implementation to the Netwide Assembler (NASM). The biggest difference between the two assemblers is AT&T-style GAS syntax vs. Intel-style NASM syntax. But I have made a couple changes. The biggest one is that nasmjf loads the jonesforth.f source file (containing the second half of the interpreter written in Forth) upon startup.

See "Loads Jones’s FORTH source on start" below.

Current status

It’s done! It passes the original JONESFORTH tests. See test.sh in the root of this repo.

Why does this exist?

Check out the devlog/log*.txt text files. They’re my rambling learning-in-public and thinking "out loud" way of describing what I’m up to. The latest log will probably give an idea of what I’m currently doing or what I’ve most recently completed.

I also wrote an article about my delightful process with this project: http://ratfactor.com/assembly-nights

I also have a placeholder for future notes and rambling thoughts about the project here: http://ratfactor.com/nasmjf

Compiling and running

You’ll need the NASM assembler, a linker such as ld, and a Linux computer (JF relies on raw syscalls). And a sense of adventure.

To build the nasmjf executabe, run build.sh. (Or see what it does.)

Manually assemble and link like so:

$ nasm -f elf32 -g -o nasmjf.o nasmjf.asm
$ ld nasmjf.o -o nasmjf
$ rm nasmjf.o

Run by calling the executable you just compiled:

$ ./nasmjf
'A' EMIT
A

If you’re going to use JONESFORTH for anything longer than a simple line or two, I highly recommend wrapping it in readline with the excellent rlwrap (https://github.com/hanslub42/rlwrap) like so:

$ rlwrap ./nasmjf

Then you’ll have line editing, history (up arrow lets you re-enter and edit the last line), and even persistent history between Forth sessions!

Loads Jones’s FORTH source on start

The implementation of JONESFORTH is in two parts: an assembly language "bootstrap" and additional essential word definitions written in FORTH.

This NASM contains a hard-coded path to the jonesforth.f FORTH source file and reads it automatically when the interpreter starts. This is to make starting and debugging the system easier and more convenient.

If you wish to disable or simply examine this change, search for lines with comments containing the string LOADJF. You can comment out most of these lines. A few will need to remain. Figuring out which is "left as an exercise for the reader", as they say.

GNU Debugger

I’ve made heavy use of the GNU Debugger to fix mistakes, understand what my program is doing, and in these early stages, it’s nearly the only way to tell what’s happening in the program at all.

I’m assembling with DWARF2 debugging info. See the r script for params.

See gdb.script for current defaults I’m using.

Show stuff:

maint info sections     # memory sections
info addr word_buffer   # address of symbol (label/var/func)
info sym 0x804c608      # reverse of info addr, symbol at addr
info var buff           # list (with addr!) of symbol names w/ "buff"
info var                # list ALL symbols
info var var_           # list all symbols that start with "var_"

Print values (register, label, literal numbers (handy as base converter)

p 0x50                  # prints 80
p/x 80                  # prints 0x50
p/x (int)some_label     # show 4 bytes (32b) of data at some_label in hex
p/x &some_label         # ADDRESS of some_label

Print value at memory location

x/x &some_label         # show a byte of data at some_label in hex
x/s &some_label         # show a string at some_label
x/4x &some_label        # show four consecutive bytes

Set temporary break and jump to location (by label)

tbreak docol
jump docol

Create GDB commands

define foo
    p $arg0
    p $arg1
end

GNU Screen

See the file screenrc in this repo to see the current convenience setup. In short, I’ve got a GDB session and Vim session open in separate windows so I can quickly toggle between them. Anything outside of those two applications is best done in a new window to keep from accidentally closing one of the two main windows.

• C-j C-j toggle between main windows

• C-j c create a new window with a shell

• C-j H start (or stop) logging window (not actually what I want)

• C-j h save hardcopy of scrollback buffer (actually what I want)

• C-j ? help (show other shortcuts)

I’m using the hardcopy feature to help me record running each milestone of progress in GDB sessions to test and document (and celebrate!) the work.

An alias called jf starts my two-windowe session like so:

alias jf='screen -c nasmjf/screenrc'

.vimrc

My whole setup on this machine is dedicated to this project. Here’s the entirety of my current .vimrc:

set tabstop=8 softtabstop=0 expandtab shiftwidth=4 smarttab
colorscheme elflord
" simple buffer switching mappings for a handful of files
nnoremap <right> :bn<cr>
nnoremap <left> :bp<cr>
" my eeepc chugs when trying to apply highlighting to this large asm file
au BufRead jonesforth.S set syntax=text nowrap
au BufRead nasmjf.listing set nowrap
let mapleader = ","

PUBLIC DOMAIN

Because Richard Jones released his work as public domain, it’s only right that I should release my port also as public domain. So here’s the license:

I, the copyright holder of this work, hereby release it into the public domain. This applies worldwide.

In case this is not legally possible, I grant any entity the right to use this work for any purpose, without any conditions, unless such conditions are required by law.