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.
Warning In order to build in modern systems it will pull the Debian 10 32bit toolchain into a local folder, this install is fairly large but can be deleted when the program is built(see make slim down below)
Requirements (host)
- x86-64 Linux,
gcc,make,python3, network access for the first build - to run the Linux build: a kernel that allows 32-bit executables (
CONFIG_IA32_EMULATION, the default on Slackware, Debian, Fedora, Arch...) and an X server (Wayland: XWayland) - nothing else: all 32-bit libraries and cross compilers are fetched into this folder
Targets
Run make help for this table.
| Linux | |
|---|---|
make |
build ./a.out and the runtime bundle lib32/ |
make run |
build and run (./run.sh) |
make appimage |
PC32-x86_64.AppImage (the program + bundle in one file) |
make install |
install the PC32 command (default PREFIX=~/.local, no root; sudo make install PREFIX=/usr/local for all users) |
make uninstall |
remove it again |
make slim |
delete sysroot32/ (~600 MB, only needed to build) |
| Windows | |
|---|---|
make win |
cross-compile PC32.exe: one static 32-bit exe, Windows 7+ (32/64-bit) |
make windist |
PC32-win32.zip: exe + a copy of the current data.blk + data/MC.bin + short readme |
make winslim |
delete mingw/ (~370 MB, only needed to build) |
make winclean |
remove PC32.exe and its objects |
| Both | |
|---|---|
make linuxdist |
PC32-linux-src.zip: source package (code, makefiles, tools, the PDF manual, vendored GLFW, data.blk, and a data/ with fnt.bin, sine.bin and MC.bin); unzip it and run make |
make dist |
AppImage + Windows zip + Linux source zip |
make clean / make distclean |
remove objects / everything generated (also the downloaded toolchains) |
make appimage downloads appimagetool and the AppImage runtime into tools/appimage/ on first use.
How the Linux build works
tools/mk32root.pydownloads the i386 Debian packages (glibc, X11, GL, GLU, mikmod, libgcc...) and unpacks them in Python (no dpkg, no root) intosysroot32/. 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/glfwwith plainmakeand linked statically, as are GLU, mikmod and libstdc++. libGL, X11 and libc stay dynamic and are copied bytools/bundle32.pytolib32/, with Mesa's 32-bit software renderer (swrast) and the loader.run.shstartsa.outthroughlib32/ld-linux.so.2, so no 32-bit system library is used. Rendering is on the CPU (LIBGL_ALWAYS_SOFTWARE=1); no GPU/OpenGL is needed on the host.a.outmust be linked non-PIE (-no-pie): the VM relies on fixed addresses.cf.sreserves its memory regions (DATABLK32 MB,PADM512 KB,VMEM8 MB) withresb;data/sine.bin(sine table) anddata/fnt.bin(font, exposed to Forth by theFONTword) are included withincbin.- 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
tools/mkmingw.pyfetches a MinGW-w64 i686 cross toolchain (gcc, binutils, headers, nasm) intomingw/;makefile.win(called bymake win) builds with it. Everything is linked statically;PC32.exeimports only system DLLs (kernel32, user32, gdi32, shell32, msvcrt, opengl32, glu32).- The VM keeps its stack-based calling convention. The stdcall Windows GL functions are wrapped
by cdecl functions in
win32_compat.h;cf.sis assembled with-DWIN32(own PE sections,_-prefixed symbols);tools/pepatch.pymarks those sections read+write+execute and turns off ASLR/DEP opt-in after linking. - Windows-specific code lives behind
#ifdef _WIN32inmain.c,%ifdef WIN32incf.s, and inwin32_compat.h; the Linux build does not use any of it.
Data files
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).
The AppImage and the Windows exe keep data.blk OUTSIDE the program, in the folder next to it
(AppImage: override with PC32_DIR=/some/dir). The AppImage creates data.blk and
data/MC.bin there on first run from copies bundled at build time. The Windows zip contains
PC32.exe, data.blk and data/MC.bin.
Using the installed PC32 command
After make install, run PC32 in any folder that has a data.blk; it uses that folder's
data.blk (and data/ for examples), so you can keep several projects in separate folders.
PC32 --new creates a fresh data.blk and data/MC.bin there (it never overwrites). The
program, its 32-bit loader/libraries and the seed files live in PREFIX/share/PC32 (about 93 MB
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.
Manual
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=1additionally writesPC32_debug.log(window/framebuffer size, GL viewport and pixel zoom on every resize/cwinscale, firstglDrawPixelssizes).- Use make debug to run it in ddd, a graphical front end to GDB, mostly unused.