DSCF.co.uk

PC32

A ColorForth compiler and editor for x86-64
git clone https://dscf.co.uk/clone/PC32.git
Home | Back | Log | Files | Refs | Issues

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:
MREADME.md | 44+++++++++++---------------------------------
DWINDOWS_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").