{"id":15060457,"url":"https://github.com/ratfactor/nasmjf","last_synced_at":"2025-10-04T19:31:23.131Z","repository":{"id":45139463,"uuid":"414646001","full_name":"ratfactor/nasmjf","owner":"ratfactor","description":"NASM port of JONESFORTH!","archived":true,"fork":false,"pushed_at":"2023-09-27T22:48:38.000Z","size":381,"stargazers_count":50,"open_issues_count":0,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-09-25T22:58:27.186Z","etag":null,"topics":["assembly-language","assembly-x86","forth","jonesforth","nasm"],"latest_commit_sha":null,"homepage":"","language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ratfactor.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-10-07T14:59:58.000Z","updated_at":"2024-06-22T23:16:51.000Z","dependencies_parsed_at":"2023-09-28T03:59:13.451Z","dependency_job_id":null,"html_url":"https://github.com/ratfactor/nasmjf","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratfactor%2Fnasmjf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratfactor%2Fnasmjf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratfactor%2Fnasmjf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratfactor%2Fnasmjf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ratfactor","download_url":"https://codeload.github.com/ratfactor/nasmjf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219876759,"owners_count":16554786,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembly-language","assembly-x86","forth","jonesforth","nasm"],"created_at":"2024-09-24T22:59:00.071Z","updated_at":"2025-10-04T19:31:22.756Z","avatar_url":"https://github.com/ratfactor.png","language":"Assembly","readme":"= nasmjf - a NASM port of JONESFORTH\n\n\n**MOVED!** Hello, I am moving my repos to http://ratfactor.com/repos/\nand setting them to read-only (\"archived\") on GitHub. Thank you, _-Dave_\n\n\nThis is a fully-functioning Forth interpreter faithfully ported from the original\nby Richard W.M. Jones:\n\nhttps://rwmj.wordpress.com/2010/08/07/jonesforth-git-repository/\n\nYou can see the full original source in the `jonesforth/` directory in this repo.\n\nAssemble and run `nasmjf` like so:\n\n----\n$ ./build.sh\n$ ./nasmjf\nJONESFORTH VERSION 1\n20643 CELLS REMAINING\nOK\n: hello .\" Hello world!\" CR ;\nhello\nHello world!\nBYE\n$\n----\n\nThis repo is a port from the original GNU Assembler (GAS) implementation to\nthe Netwide Assembler (NASM). The biggest difference between the two assemblers\nis AT\u0026T-style GAS syntax vs. Intel-style NASM syntax. But I have made a couple\nchanges. The biggest one is that `nasmjf` loads the `jonesforth.f` source file\n(containing the second half of the interpreter written in Forth) upon startup.\n\nSee \"Loads Jones's FORTH source on start\" below.\n\n\n\n== Current status\n\nIt's done! It passes the original JONESFORTH tests. See\n`test.sh` in the root of this repo.\n\n\n== Why does this exist?\n\nCheck out the `devlog/log*.txt` text files. They're my rambling learning-in-public and\nthinking \"out loud\" way of describing what I'm up to. The latest log will probably\ngive an idea of what I'm currently doing or what I've most recently completed.\n\nI also wrote an article about my delightful process with this project:\nhttp://ratfactor.com/assembly-nights\n\nI also have a placeholder for future notes and rambling thoughts about the project here:\nhttp://ratfactor.com/nasmjf\n\n\n== Compiling and running\n\nYou'll need the NASM assembler, a linker such as `ld`, and a Linux computer\n(JF relies on raw syscalls). And a sense of adventure.\n\nTo build the `nasmjf` executabe, run `build.sh`. (Or see what it does.)\n\nManually assemble and link like so:\n\n----\n$ nasm -f elf32 -g -o nasmjf.o nasmjf.asm\n$ ld nasmjf.o -o nasmjf\n$ rm nasmjf.o\n----\n\nRun by calling the executable you just compiled:\n\n----\n$ ./nasmjf\n'A' EMIT\nA\n----\n\nIf you're going to use JONESFORTH for anything longer than a simple line or\ntwo, I _highly_ recommend wrapping it in `readline` with the excellent `rlwrap`\n(https://github.com/hanslub42/rlwrap) like so:\n\n----\n$ rlwrap ./nasmjf\n----\n\nThen you'll have line editing, history (up arrow lets you re-enter and edit the\nlast line), and even persistent history between Forth sessions!\n\n== Loads Jones's FORTH source on start\n\nThe implementation of JONESFORTH is in two parts: an assembly language\n\"bootstrap\" and additional essential word definitions written in FORTH.\n\nThis NASM contains a hard-coded path to the `jonesforth.f` FORTH source file\nand reads it automatically when the interpreter starts. This is to make\nstarting and debugging the system easier and more convenient.\n\nIf you wish to disable or simply examine this change, search for lines with\ncomments containing the string `LOADJF`. You can comment out most of these\nlines. A few will need to remain. Figuring out which is \"left as an exercise\nfor the reader\", as they say.\n\n\n\n\n== GNU Debugger\n\nI've made heavy use of the GNU Debugger to fix mistakes, understand what\nmy program is doing, and in these early stages, it's nearly the only way\nto tell what's happening in the program at all.\n\nI'm assembling with DWARF2 debugging info. See the `r` script for params.\n\nSee `gdb.script` for current defaults I'm using.\n\nShow stuff:\n\n    maint info sections     # memory sections\n    info addr word_buffer   # address of symbol (label/var/func)\n    info sym 0x804c608      # reverse of info addr, symbol at addr\n    info var buff           # list (with addr!) of symbol names w/ \"buff\"\n    info var                # list ALL symbols\n    info var var_           # list all symbols that start with \"var_\"\n\nPrint values (register,  label, literal numbers (handy as base converter)\n\n    p 0x50                  # prints 80\n    p/x 80                  # prints 0x50\n    p/x (int)some_label     # show 4 bytes (32b) of data at some_label in hex\n    p/x \u0026some_label         # ADDRESS of some_label\n\nPrint value at memory location\n\n    x/x \u0026some_label         # show a byte of data at some_label in hex\n    x/s \u0026some_label         # show a string at some_label\n    x/4x \u0026some_label        # show four consecutive bytes\n\nSet temporary break and jump to location (by label)\n\n    tbreak docol\n    jump docol\n\nCreate GDB commands\n\n    define foo\n        p $arg0\n        p $arg1\n    end\n\n\n== GNU Screen\n\nSee the file `screenrc` in this repo to see the current convenience setup.\nIn short, I've got a GDB session and Vim session open in separate windows\nso I can quickly toggle between them. Anything outside of those two\napplications is best done in a new window to keep from accidentally closing\none of the two main windows.\n\n* `C-j C-j` toggle between main windows\n* `C-j c` create a new window with a shell\n* `C-j H` start (or stop) logging window (not actually what I want)\n* `C-j h` save hardcopy of scrollback buffer (actually what I want)\n* `C-j ?` help (show other shortcuts)\n\nI'm using the hardcopy feature to help me record running each milestone of\nprogress in GDB sessions to test and document (and celebrate!) the work.\n\nAn alias called `jf` starts my two-windowe session like so:\n\n----\nalias jf='screen -c nasmjf/screenrc'\n----\n\n== .vimrc\n\nMy whole setup on this machine is dedicated to this project.\nHere's the entirety of my current `.vimrc`:\n\n----\nset tabstop=8 softtabstop=0 expandtab shiftwidth=4 smarttab\ncolorscheme elflord\n\" simple buffer switching mappings for a handful of files\nnnoremap \u003cright\u003e :bn\u003ccr\u003e\nnnoremap \u003cleft\u003e :bp\u003ccr\u003e\n\" my eeepc chugs when trying to apply highlighting to this large asm file\nau BufRead jonesforth.S set syntax=text nowrap\nau BufRead nasmjf.listing set nowrap\nlet mapleader = \",\"\n----\n\n\n\n== PUBLIC DOMAIN\n\nBecause Richard Jones released his work as public domain, it's only right\nthat I should release my port also as public domain. So here's the license:\n\nI, the copyright holder of this work, hereby release it into the public domain.\nThis applies worldwide.\n\nIn case this is not legally possible, I grant any entity the right to use this\nwork for any purpose, without any conditions, unless such conditions are\nrequired by law.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fratfactor%2Fnasmjf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fratfactor%2Fnasmjf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fratfactor%2Fnasmjf/lists"}