commit f5d1e4bc3f8e46a957b9268e0f286612f8ce020e
parent 64adc5f0f7ebf8674fa7561900c6c0109b4eecae
Author: Julian <tide@dscf.co.uk>
Date: Fri, 20 Nov 2026 19:16:15 -0500
Moving over to local hosting
Diffstat:
| M | README.md | | | 44 | +++++++++++--------------------------------- |
| D | WINDOWS_PORT.md | | | 119 | ------------------------------------------------------------------------------- |
2 files changed, 11 insertions(+), 152 deletions(-)
diff --git a/README.md b/README.md
@@ -1,10 +1,9 @@
-# PC32 ColorForth - Linux and Windows builds, no multilib
+# PC32 ColorForth - Linux and Windows builds
+
+A simple ColorForth compiler and editor for x86, it assembles its own instructions and runs fairly fast,
+this repo contains the ported version that should build on modern x64 linux and windows machines,
+original targets were debian 10 and windows 7.
-The VM (`cf.s`) is 32-bit only: it emits x86-32 machine code and passes arguments on the
-stack, so it cannot be ported to x86-64. Modern 64-bit distros usually lack the 32-bit
-glibc/GL/X11 libraries (multilib), so this tree builds and runs the 32-bit program anyway,
-entirely inside this directory, without root and without cmake. The same tree also
-cross-compiles a Windows `.exe`.
## Requirements (host)
- x86-64 Linux, `gcc`, `make`, `python3`, network access for the first build
@@ -41,8 +40,8 @@ Run `make help` for this table.
## How the Linux build works
- `tools/mk32root.py` downloads the i386 Debian packages (glibc, X11, GL, GLU, mikmod, libgcc...)
- and unpacks them in pure Python (no dpkg, no root) into `sysroot32/`. On filesystems without
- symlinks (e.g. VirtualBox shared folders) links are replaced by copies. It is only a source
+ and unpacks them in Python (no dpkg, no root) into `sysroot32/`. On filesystems without
+ symlinks links are replaced by copies. It is only a source
of 32-bit headers and libraries.
- GLFW 3.3.8 is compiled from `third_party/glfw` with plain `make` and linked statically, as are
GLU, mikmod and libstdc++.
@@ -57,7 +56,7 @@ Run `make help` for this table.
- The AppImage stages its AppDir in a temp dir (appimagetool needs symlinks) and keeps the data
files outside the image (below).
-## How the Windows build works (details: `WINDOWS_PORT.md`)
+## How the Windows build works
- `tools/mkmingw.py` fetches a MinGW-w64 i686 cross toolchain (gcc, binutils, headers, nasm) into
`mingw/`; `makefile.win` (called by `make win`) builds with it. Everything is linked
statically; `PC32.exe` imports only system DLLs (kernel32, user32, gdi32, shell32, msvcrt,
@@ -70,7 +69,7 @@ Run `make help` for this table.
`win32_compat.h`; the Linux build does not use any of it.
## Data files
-Only `data.blk` (your source/state) is needed. It is read and written in the working directory.
+Only `data.blk` (source/state) is needed. It is read and written in the working directory.
The font (`fnt.bin`), the sine table (`sine.bin`) and the memory regions are built into the
program, so no other file is required. `data/MC.bin` is shipped as example data for the Forth
examples that use it (it is optional; if a word opens a missing file, `copen` creates it empty).
@@ -88,34 +87,13 @@ program, its 32-bit loader/libraries and the seed files live in `PREFIX/share/PC
on disk), the launcher is `PREFIX/bin/PC32`; if `PREFIX/bin` is not in your `PATH`, `make install`
says so. Any extra argument (e.g. `PC32 -w`) starts a normal window instead of a maximized one.
-## Gotchas found while porting
-- **VM data stack:** `cf.s` (`COLD`) puts the Forth data stack at `esp+512`, i.e. in the C stack
- above `comp`'s frame. With small caller frames that range reaches `argv`/`envp`; the VM
- overwrote them and libGL's `getenv()` crashed on the first GL call, but only for some launch
- modes. `main.c` reserves 2 KB with `alloca` right before `comp()` so the range lies in scratch
- space.
-- **Windows window size:** an undecorated GLFW window there is a `WS_POPUP` without a maximize
- box, so `GLFW_MAXIMIZED` does nothing and even blocks resizing; `win_fit_window()` sizes it to
- the monitor work area. The VM only learns of a resize from inside its own event loop, so
- `win_pollevents` re-sends the size on the first few polls.
-- **One builder per folder:** build in one place and only run the result elsewhere. Building on
- a symlink-capable system and on a shared folder without symlinks in the same tree leaves
- `sysroot32/` unreadable for one of them (delete it and rebuild).
-
## Manual
-`docs/PC32_Manual.pdf` describes how the compiler and the `data.blk` block format work. It (and an
-editable `.odt`) is generated from `data.blk` and `docs/content.py` by `python3 -I docs/build_docs.py`
-(python3 with pycairo and PyGObject/Pango; the ODT part needs nothing extra). The source package
-contains only the finished PDF, not the generator or the ODT.
+`docs/PC32_Manual.pdf` describes how the compiler and the `data.blk` block format work.
## Debugging
- A crash writes `PC32_crash.log` (registers, stack, memory map or module) to the working
directory (for the AppImage: next to it).
- `PC32_DEBUG=1` additionally writes `PC32_debug.log` (window/framebuffer size, GL viewport and
pixel zoom on every resize/`cwinscale`, first `glDrawPixels` sizes).
+- Use make debug to run it in ddd, a graphical front end to GDB, mostly unused.
-## Layout
-`cf.s` VM, `main.c` host program, `win32_compat.h` Windows glue, `debuglog.h` opt-in log,
-`makefile` (Linux + entry points), `makefile.win`, `run.sh`, `tools/` (sysroot, toolchain,
-bundle, zip, pe patch, AppImage files, dist readme), `third_party/glfw`, `data/`.
-`editor/` is an old tool and is not used.
diff --git a/WINDOWS_PORT.md b/WINDOWS_PORT.md
@@ -1,119 +0,0 @@
-# Windows build - plan / handoff
-
-## STATUS (working: runs on Windows, window sizing fixed)
-`make win` (or `make -f makefile.win`) cross-compiles `PC32.exe` here: one static PE32 (i386) console
-executable, imports only system DLLs (kernel32, user32, gdi32, shell32, msvcrt, opengl32, glu32).
-Tested by the user on a real Windows machine (the Linux VM has no Windows/Wine). What exists:
-- `tools/mkmingw.py` fetches the toolchain into `./mingw` (gcc 8.3 win32-threads, binutils 2.31,
- headers, nasm); `make win` does it automatically.
-- `makefile.win` (separate from the Linux makefile; `make win` / `make winclean` call it).
-- `win32_compat.h`: cdecl wrappers for the stdcall GL calls (`GLF()`), mikmod stubs, `usleep`, GL 1.2
- constants, crash log via `SetUnhandledExceptionFilter` (-> `PC32_crash.log`), `win_startup()`
- (chdir to exe folder, binary fopen mode).
-- `main.c`: `#ifdef _WIN32` include block, `GLF(...)` around the GL functions the VM calls,
- Linux-only crash handler wrapped, `win_startup()` call. Linux behaviour unchanged.
-- `cf.s`: `%ifdef WIN32` gives it its own PE sections (.pc32t code, .pc32d data) because COFF
- can't align sections past 64 bytes; `PAGEALIGN` macro replaces `align 4096`. Assembled with
- `nasm -f win32 --prefix _ -DWIN32` (the `_` prefix covers comp/cprint/DATABLK/...).
-- `tools/pepatch.py` (post-link): sets .pc32t/.pc32d to read+write+execute (nasm 2.14's win32
- format ignores the section attributes) and clears DYNAMIC_BASE/NX_COMPAT (Debian's binutils turns
- them on and has no option to turn them off).
-- Layout check: DATABLK is page aligned and WIDTH/HEIGHT/CDATA sit at the same offsets as on Linux.
-
-### Findings from bringing it up on Windows
-- **Window size**: an undecorated GLFW window on Windows is `WS_POPUP` with no maximize box.
- `GLFW_MAXIMIZED` / `ShowWindow(SW_MAXIMIZE)` do nothing useful, and passing `GLFW_MAXIMIZED`
- marks the window maximized so `SetWindowPos` can't resize it. So on Windows `main.c` does NOT
- pass that hint and sizes/positions the window to the monitor work area by hand.
-- **Resize event timing**: on Linux the first "window resized" event arrives after the VM is
- running and Forth reacts to the `CDATA[0]` flag (re-reads WX/WY, calls `winscale` -> viewport).
- On Windows the size is set before the VM starts, so `win_pollevents` (the VM's `glfwPollEvents`)
- re-sends the size for the first five polls.
-- **Debug log**: `PC32_DEBUG=1` writes `PC32_debug.log` (window/framebuffer size, IWIDTH/IHEIGHT, GL
- viewport + zoom on every resize/cwinscale, first glDrawPixels sizes; code in `debuglog.h`). Off by
- default on all platforms. It is what found the window-size problem.
-- Targets: `make win`, `make windist` (zip), `make winslim` (delete `mingw/`), `make winclean`.
-- The GL calls Forth makes (glDrawPixels with `GL_UNSIGNED_SHORT_5_5_5_1`, a GL 1.2 type) work on
- the tested machine; a Windows install with only the generic GL 1.1 renderer may not draw them.
-
-### Original checklist (first things to check on a real Windows machine) (Win7 32/64 VM and Win10/11)
-1. Does it start? Put `PC32.exe` next to `data.blk` (and `data/MC.bin` for the examples). A crash writes
- `PC32_crash.log` next to the exe (exception code, address, module, registers, stack).
-2. DEP / RWX data: if it dies executing in `.pc32d`, check the section flags with the log.
-3. GL calls: the cdecl wrappers are the likeliest source of mismatched-argument crashes.
-4. Antivirus (Defender) reaction to the RWX sections; consider signing + version info.
-5. VM without 3D acceleration = Microsoft generic OpenGL 1.1 (slow but a good worst case).
-6. Console window: it is a console-subsystem exe (so printf output is visible); add `-mwindows`
- later if a console-less build is wanted.
-
-
-Goal: `PC32.exe`, a single 32-bit executable for Windows 7+ (runs on 32- and 64-bit Windows via
-WoW64), built by cross-compiling from the Linux VM with plain `make` (no cmake). Distributed
-as the exe plus the data files next to it, like the AppImage. The Linux build must keep working.
-
-## Decisions already made
-- Cross-compile here with MinGW-w64 (`i686-w64-mingw32-gcc`) and `nasm -f win32`; test the exe in a
- Windows 7 VM and on a real Windows 10/11 machine. Don't build inside Windows.
-- Everything static: C runtime (`-static`), GLFW (built from source, Windows backend), GLU if
- needed. Only system DLLs remain: opengl32, glu32, kernel32, user32, gdi32, shell32, winmm...
-- Use the default `msvcrt.dll` MinGW target (present on every Windows), NOT the UCRT toolchain
- (Windows 7 lacks UCRT without updates). Compile with `-D_WIN32_WINNT=0x0601`.
-- Do NOT bundle opengl32.dll/glu32.dll (they come from the OS/driver). Optional separate download:
- a software Mesa `opengl32.dll` placed next to the exe for machines with no usable OpenGL.
-- Toolchain is fetched into the project folder (same approach as `tools/mk32root.py`: download
- Debian packages, unpack in pure Python, no root). The shared folder has no symlinks, so use
- the copy-instead-of-symlink logic already in that script. Build in ONE place only.
-
-## Hard constraints (do not break)
-- **Arguments are passed on the stack.** The whole VM is built around it: Forth words push
- arguments to the stack and call C functions, the ABI is 32-bit stack-based (cdecl-style). Keep that
- everywhere: no register-passing conventions (no fastcall/vectorcall), nothing that changes how
- `cf.s` calls C or how C calls `comp`. Any adaptation for Windows APIs (stdcall GL functions,
- etc.) goes in C-side cdecl wrapper functions that take their arguments from the stack and call
- the real function; the VM and the Forth source (`data.blk`) stay untouched.
-- **The Linux build must keep working exactly as it does now** (`make`, `make run`, `make appimage`,
- `make slim`). Windows support is additive: platform differences live behind `#ifdef _WIN32` in
- `main.c` and a small `%ifdef`/macro layer in `cf.s` (e.g. the `_` symbol prefix), selected by a
- nasm `-d` flag from the Windows target only. The default Linux targets must not need any change
- or any Windows toolchain, and after every Windows change re-run the Linux build and compare it
- (it must still start, draw, and use the 3D words).
-- Keep `a.out` non-PIE and the `alloca` stack pad before `comp()` on both platforms.
-
-## Work items
-1. **Toolchain fetch**: extend/clone `tools/mk32root.py` for `gcc-mingw-w64-i686` (+ binutils,
- headers, crt, winpthreads if needed). Host-side 64-bit binaries run fine here.
-2. **GLFW**: restore the Windows sources removed from `third_party/glfw/src` (win32_*.c, wgl_context.c,
- egl_context.c, osmesa_context.c) from the 3.3.8 tarball; compile with `-D_GLFW_WIN32`.
-3. **cf.s** (the VM):
- - C symbols are `_`-prefixed on win32 (`comp`, `cprint`, `DATABLK`, `HEIGHT`, `WIDTH`, `CDATA`):
- add `%define`/macro so the Linux build keeps the plain names.
- - The data section is executed (the VM compiles code into it): needs a read-write-EXECUTE section
- in the PE (nasm section flags + linker). Test early on Windows 7 with DEP on.
- - Memory regions are `resb` blocks (DATABLK 32 MB, PADM 512 KB, VMEM 8 MB); check they link as
- a PE section of that size.
-4. **main.c**:
- - Calling convention: the VM calls C functions cdecl (caller cleans the stack). Windows GL
- entry points are `stdcall` (callee cleans) - calling them straight from Forth unbalances the
- stack. Add cdecl wrappers for every GL/GLU function passed to `INTERN(...)` on Windows.
- - `usleep`, `unistd.h`, `sys/time.h`, `signal.h` features: provide Windows equivalents
- (`Sleep`). The crash handler uses `ucontext`/`/proc/self/maps` -> on Windows use
- `SetUnhandledExceptionFilter` and write the same `PC32_crash.log` (registers, stack).
- - Keep the `alloca(2048)` pad before `comp()` - the VM data stack lives at `esp+512` and would
- otherwise overwrite whatever sits above (argv/envp on Linux; unknown on Windows).
- - `mikmod.h` / `Player_*` references: no Windows mikmod; stub them (sound is already commented
- out in `main.c`) or add a real mikmod build later.
- - `GLFW_DECORATED` hint is passed `NULL`; fine, but check on Windows.
- - `fopen(...,"rb"/"wb")`: binary modes already used; paths are relative to the exe folder -
- set the working directory to the exe's folder at startup (like AppRun does on Linux).
-5. **makefile**: add `make win` -> `PC32.exe` (and `make winclean`); keep Linux targets unchanged.
-6. **Test matrix**: Win7 32-bit VM (no 3D accel = Microsoft generic OpenGL 1.1: worst case), Win7 64,
- Win10/11 real GPU. Check antivirus (Defender) on the exe: RWX section + self-modifying code
- may trigger false positives; consider code signing and proper version info/manifest.
-
-## Facts about the existing project worth knowing
-- Linux build: `make` -> `a.out` + `lib32/` bundle; `make appimage`; `make slim` removes `sysroot32/`.
-- `editor/` is an old tool; its `cf_win.s` is for an OLD 64-bit VM - not usable.
-- Runtime data: only `data.blk` is required (the font, sine table and memory are built into the binary);
- `data/MC.bin` is example data. Files that old test words in `data.blk` mention (geo.bin, pdata.bin,
- tex.bin, test.bmp, res/click.wav) are not needed.
-- Known pitfall: VM data stack at `esp+512` clobbered argv/envp (see README "Gotchas").