dbetz · blakemcbride · Dec 24, 2025
diff --git a/Makefile b/Makefile
@@ -45,7 +45,12 @@ endif
 ECHO=echo
 MKDIR=mkdir
 
-CFLAGS=-Wall -DUNIX -I$(HDRDIR)
+CFLAGS=-Wall -DUNIX -I$(HDRDIR) -fPIC
+
+# Reentrant/threading support: make REENTRANT=1
+ifdef REENTRANT
+  CFLAGS += -DXLISP_USE_CONTEXT
+endif
 
 INC=$(HDRDIR)/xlisp.h
 
@@ -67,6 +72,7 @@ clean:
 	rm -f -r $(OBJDIR)
 	rm -f -r $(LIBDIR)
 	rm -f -r $(BINDIR)
+	rm -f -r build
 
 #########
 # XLISP #
@@ -99,6 +105,7 @@ $(LIBOBJDIR)/xlansi.o \
 $(LIBOBJDIR)/xlapi.o \
 $(LIBOBJDIR)/xlcobj.o \
 $(LIBOBJDIR)/xlcom.o \
+$(LIBOBJDIR)/xlcontext.o \
 $(LIBOBJDIR)/xldbg.o \
 $(LIBOBJDIR)/xldmem.o \
 $(LIBOBJDIR)/xlfasl.o \

diff --git a/README.md b/README.md
@@ -1,53 +1,39 @@
-# xlisp
-## An object-oriented LISP
+# XLISP 3
 
-Version 3.0
+XLISP3 is a fork of David Betz's XLISP3.
 
-February 18, 2006
+The home for this fork is at <https://github.com/blakemcbride/XLISP3>
 
-## Building with CMake
-We've added the ability to build with CMake to simplify building XLisp on your
-system. The way that we expect this to work on Linux systems using `make` would
-be to first make a build directory. For this walkthrough we'll say that we
-start _in_ the xlisp directory:
+XLISP3 is better described as Scheme than Lisp since it more closely follows Scheme.
 
-```bash
-cd ..
-mkdir build
-cd build
-ccmake ../xlisp
-```
-So, now we have made a build directory outside of xlisp, so that the build
-products don't get strewn all over our pristine source. The `ccmake` command is
-a curses front end to CMake that I like. From there you can pick the type of
-build, then type "g" for generate. This drops you out in a shell prompt, where
-it has made makefiles for you (on other platforms, you may have other types of
-build files generated). After that you can:
+It has some really nice features as follows:
 
-```bash
-make
-# and then, either:
-make install
-# or
-make package
-```
+1. It has a byte-code compiler (to FASL files) so code runs reasonably fast.
+2. It can load Lisp source files or compiled FASL files.
+3. It has an object system with classes, methods, inheritance, and `super` calls.
+4. The macro system is traditional Lisp-style (not Scheme's hygienic macros).
+5. It can be used as an extension language embedded in C programs.
+6. It can save/load workspace images.
+7. It correctly handles tail recursion (proper tail call optimization).
+8. It has a Common Lisp-style package system.
+9. It supports multiple return values.
+10. It has first-class continuations (call/cc).
 
-With the CMake file we have in there, it also has a "package" target, which
-will most likely result in a gzipped tar file of the build products. It is also
-possible to alter the `CMakeLists.txt` file to generate other package types,
-such as `*.rpm`, `*.deb`, etc.
+## To all of this, I have added:
 
-#### David Michael Betz
+A. When used as an extension language, it is now reentrant and can handle multiple simultaneous threads.
 
-18 Garrison Drive
-Bedford, US, NH 03110
+To this, I would like to add native thread support at some time.
 
-(603) 472-2389 (home)
+## Building
 
-#### Copyright (c) 1984-2006, by David Michael Betz
+    make                 # standard build
+    make REENTRANT=1     # thread-safe build
+    make clean           # remove build artifacts
 
-All Rights Reserved
+## The original README file is located at README2.md
+
+Blake McBride
+blake@mcbridemail.com
 
-See the included file LICENSE for the full license.
 
-Updated 11/8/24 to test 2FA.
diff --git a/README2.md b/README2.md
@@ -0,0 +1,53 @@
+# xlisp
+## An object-oriented LISP
+
+Version 3.0
+
+February 18, 2006
+
+## Building with CMake
+We've added the ability to build with CMake to simplify building XLisp on your
+system. The way that we expect this to work on Linux systems using `make` would
+be to first make a build directory. For this walkthrough we'll say that we
+start _in_ the xlisp directory:
+
+```bash
+cd ..
+mkdir build
+cd build
+ccmake ../xlisp
+```
+So, now we have made a build directory outside of xlisp, so that the build
+products don't get strewn all over our pristine source. The `ccmake` command is
+a curses front end to CMake that I like. From there you can pick the type of
+build, then type "g" for generate. This drops you out in a shell prompt, where
+it has made makefiles for you (on other platforms, you may have other types of
+build files generated). After that you can:
+
+```bash
+make
+# and then, either:
+make install
+# or
+make package
+```
+
+With the CMake file we have in there, it also has a "package" target, which
+will most likely result in a gzipped tar file of the build products. It is also
+possible to alter the `CMakeLists.txt` file to generate other package types,
+such as `*.rpm`, `*.deb`, etc.
+
+#### David Michael Betz
+
+18 Garrison Drive
+Bedford, US, NH 03110
+
+(603) 472-2389 (home)
+
+#### Copyright (c) 1984-2006, by David Michael Betz
+
+All Rights Reserved
+
+See the included file LICENSE for the full license.
+
+Updated 11/8/24 to test 2FA.
diff --git a/doc/CODEBASE_ANALYSIS.md b/doc/CODEBASE_ANALYSIS.md
@@ -0,0 +1,153 @@
+# XLISP Codebase Analysis
+
+## Overview
+
+**XLISP** is an object-oriented LISP interpreter/compiler (v3.3) by David Michael Betz (1983-2017). Licensed under MIT. It compiles Lisp to bytecodes rather than interpreting directly, making it faster than traditional interpreters.
+
+## Project Structure
+
+```
+xlisp/
+├── src/           # Core C source (27 files, ~18.8K lines)
+├── include/       # Header files
+├── xlisp/         # REPL executable source
+├── ext/           # Extension module
+├── doc/           # Documentation (Markdown)
+├── *.lsp          # 14 Lisp initialization/library files
+├── CMakeLists.txt # Modern build system
+└── Makefile       # Legacy build
+```
+
+## Key Components
+
+| Module | Purpose |
+|--------|---------|
+| `xlcom.c` | Bytecode compiler |
+| `xlint.c` | Bytecode interpreter/VM |
+| `xldmem.c` | Memory management & GC |
+| `xlobj.c` | Object-oriented system |
+| `xlread.c` / `xlprint.c` | Reader/printer |
+| `xlapi.c` | C embedding API |
+| `xlfun1.c`, `xlfun2.c`, `xlfun3.c` | Built-in functions |
+| `xlftab.c` | Function table registry |
+| `xlmath.c` | Mathematical functions |
+| `xlsym.c` | Symbol and package management |
+| `xlimage.c` | Memory image/workspace management |
+| `xlfasl.c` | Fast loading (compiled bytecode) |
+| `xldbg.c` | Debugging support |
+| `msstuff.c` | Windows-specific code |
+| `unstuff.c` | Unix-specific code |
+
+## Lisp Library Files
+
+| File | Purpose |
+|------|---------|
+| `xlisp.lsp` | Main initialization |
+| `xlinit.lsp` | System initialization |
+| `macros.lsp` | Macro system |
+| `objects.lsp` | Object system utilities |
+| `qquote.lsp` | Quasiquote/unquote support |
+| `clisp.lsp` | Common Lisp compatibility |
+| `pp.lsp` | Pretty printer |
+| `math.lsp` | Math utilities |
+| `compile.lsp` | Compilation utilities |
+| `fasl.lsp` | Fast loading utilities |
+| `crec.lsp` | C records (FFI) |
+
+## Architecture
+
+### Execution Flow
+
+```
+Lisp Source Code
+       ↓
+   Reader (xlread.c)
+       ↓
+  S-Expressions
+       ↓
+ Compiler (xlcom.c)
+       ↓
+    Bytecodes
+       ↓
+ Interpreter (xlint.c)
+       ↓
+ Execution Results
+```
+
+### Memory Layout
+
+- **Node Space**: Lisp values with free list and protected pointers
+- **Vector Space**: Strings and arrays with automatic expansion
+- **Generational garbage collection**
+
+### VM Registers
+
+- `xlFun` - current function
+- `xlEnv` - environment
+- `xlVal` - last value
+- `xlSP` - value stack pointer
+- `xlCSP` - control stack pointer
+
+## Notable Features
+
+- **Bytecode compilation** - not direct interpretation
+- **Generational garbage collection** with protected pointers
+- **Class-based OOP** with inheritance and method dispatch
+- **Scheme influences** - lexical scoping, proper tail recursion
+- **Common Lisp elements** - packages, keywords, multiple values
+- **Cross-platform** (Windows, Linux, macOS) via ANSI C
+- **Extensible** via C API and extension modules
+- **FASL support** - fast loading of pre-compiled bytecode
+
+## Build System
+
+### CMake (Recommended)
+
+```bash
+mkdir build && cd build
+cmake ..
+make
+make install  # or make package
+```
+
+Requires CMake 3.14+. Supports link-time optimization (IPO).
+
+### Build Targets
+
+1. **xlisp** (library) - Core interpreter/compiler
+2. **ext** (shared library) - Extension module
+3. **xlisp-repl** (executable) - Interactive REPL
+
+### Legacy Support
+
+- `Makefile` - Traditional make-based build
+- `.dsp/.dsw` - Historical Visual Studio project files
+
+## Type System
+
+- `xlValue` - Universal Lisp value pointer (node-based)
+- `xlFIXTYPE` - Fixed-point integers (long)
+- `xlFLOTYPE` - Floating-point (double)
+- `xlCHRTYPE` - Character (int)
+
+## C API Patterns
+
+```c
+// Argument fetching
+xlGetArg()
+xlGetArgFixnum()
+xlLastArg()  // Detects too many args
+
+// Return values
+xlMakeFixnum()
+xlCons()
+
+// Class definition
+xlClass()
+```
+
+## Platform Abstraction
+
+- `msstuff.c` - Windows-specific implementation
+- `unstuff.c` - Unix-specific implementation
+- ANSI C for maximum portability