README.md (6073B)
1 # PC32 ColorForth - Linux and Windows builds 2 3 A simple ColorForth compiler and editor for x86, it assembles its own instructions and runs fairly fast, 4 this repo contains the ported version that should build on modern x64 linux and windows machines, 5 original targets were debian 10 and windows 7. 6 7 ** Warning ** 8 In order to build in modern systems it will pull the Debian 10 32bit toolchain into a local folder, 9 this install is fairly large but can be deleted when the program is built(see make slim down below) 10 11 12 ## Requirements (host) 13 - x86-64 Linux, `gcc`, `make`, `python3`, network access for the first build 14 - to *run* the Linux build: a kernel that allows 32-bit executables (`CONFIG_IA32_EMULATION`, 15 the default on Slackware, Debian, Fedora, Arch...) and an X server (Wayland: XWayland) 16 - nothing else: all 32-bit libraries and cross compilers are fetched into this folder 17 18 ## Targets 19 Run `make help` for this table. 20 21 | Linux | | 22 |---|---| 23 | `make` | build `./a.out` and the runtime bundle `lib32/` | 24 | `make run` | build and run (`./run.sh`) | 25 | `make appimage` | `PC32-x86_64.AppImage` (the program + bundle in one file) | 26 | `make install` | install the `PC32` command (default `PREFIX=~/.local`, no root; `sudo make install PREFIX=/usr/local` for all users) | 27 | `make uninstall` | remove it again | 28 | `make slim` | delete `sysroot32/` (~600 MB, only needed to build) | 29 30 | Windows | | 31 |---|---| 32 | `make win` | cross-compile `PC32.exe`: one static 32-bit exe, Windows 7+ (32/64-bit) | 33 | `make windist` | `PC32-win32.zip`: exe + a copy of the current `data.blk` + `data/MC.bin` + short readme | 34 | `make winslim` | delete `mingw/` (~370 MB, only needed to build) | 35 | `make winclean` | remove `PC32.exe` and its objects | 36 37 | Both | | 38 |---|---| 39 | `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` | 40 | `make dist` | AppImage + Windows zip + Linux source zip | 41 | `make clean` / `make distclean` | remove objects / everything generated (also the downloaded toolchains) | 42 43 `make appimage` downloads `appimagetool` and the AppImage runtime into `tools/appimage/` on first use. 44 45 ## How the Linux build works 46 - `tools/mk32root.py` downloads the i386 Debian packages (glibc, X11, GL, GLU, mikmod, libgcc...) 47 and unpacks them in Python (no dpkg, no root) into `sysroot32/`. On filesystems without 48 symlinks links are replaced by copies. It is only a source 49 of 32-bit headers and libraries. 50 - GLFW 3.3.8 is compiled from `third_party/glfw` with plain `make` and linked statically, as are 51 GLU, mikmod and libstdc++. 52 - `libGL`, X11 and libc stay dynamic and are copied by `tools/bundle32.py` to `lib32/`, with 53 Mesa's 32-bit software renderer (`swrast`) and the loader. `run.sh` starts `a.out` through 54 `lib32/ld-linux.so.2`, so no 32-bit system library is used. Rendering is on the CPU 55 (`LIBGL_ALWAYS_SOFTWARE=1`); no GPU/OpenGL is needed on the host. 56 - `a.out` must be linked non-PIE (`-no-pie`): the VM relies on fixed addresses. 57 - `cf.s` reserves its memory regions (`DATABLK` 32 MB, `PADM` 512 KB, `VMEM` 8 MB) with `resb`; 58 `data/sine.bin` (sine table) and `data/fnt.bin` (font, exposed to Forth by the `FONT` word) 59 are included with `incbin`. 60 - The AppImage stages its AppDir in a temp dir (appimagetool needs symlinks) and keeps the data 61 files outside the image (below). 62 63 ## How the Windows build works 64 - `tools/mkmingw.py` fetches a MinGW-w64 i686 cross toolchain (gcc, binutils, headers, nasm) into 65 `mingw/`; `makefile.win` (called by `make win`) builds with it. Everything is linked 66 statically; `PC32.exe` imports only system DLLs (kernel32, user32, gdi32, shell32, msvcrt, 67 opengl32, glu32). 68 - The VM keeps its stack-based calling convention. The stdcall Windows GL functions are wrapped 69 by cdecl functions in `win32_compat.h`; `cf.s` is assembled with `-DWIN32` (own PE sections, 70 `_`-prefixed symbols); `tools/pepatch.py` marks those sections read+write+execute and turns 71 off ASLR/DEP opt-in after linking. 72 - Windows-specific code lives behind `#ifdef _WIN32` in `main.c`, `%ifdef WIN32` in `cf.s`, and in 73 `win32_compat.h`; the Linux build does not use any of it. 74 75 ## Data files 76 Only `data.blk` (source/state) is needed. It is read and written in the working directory. 77 The font (`fnt.bin`), the sine table (`sine.bin`) and the memory regions are built into the 78 program, so no other file is required. `data/MC.bin` is shipped as example data for the Forth 79 examples that use it (it is optional; if a word opens a missing file, `copen` creates it empty). 80 81 The AppImage and the Windows exe keep `data.blk` OUTSIDE the program, in the folder next to it 82 (AppImage: override with `PC32_DIR=/some/dir`). The AppImage creates `data.blk` and 83 `data/MC.bin` there on first run from copies bundled at build time. The Windows zip contains 84 `PC32.exe`, `data.blk` and `data/MC.bin`. 85 86 ### Using the installed `PC32` command 87 After `make install`, run `PC32` in any folder that has a `data.blk`; it uses that folder's 88 `data.blk` (and `data/` for examples), so you can keep several projects in separate folders. 89 `PC32 --new` creates a fresh `data.blk` and `data/MC.bin` there (it never overwrites). The 90 program, its 32-bit loader/libraries and the seed files live in `PREFIX/share/PC32` (about 93 MB 91 on disk), the launcher is `PREFIX/bin/PC32`; if `PREFIX/bin` is not in your `PATH`, `make install` 92 says so. Any extra argument (e.g. `PC32 -w`) starts a normal window instead of a maximized one. 93 94 ## Manual 95 `docs/PC32_Manual.pdf` describes how the compiler and the `data.blk` block format work. 96 97 ## Debugging 98 - A crash writes `PC32_crash.log` (registers, stack, memory map or module) to the working 99 directory (for the AppImage: next to it). 100 - `PC32_DEBUG=1` additionally writes `PC32_debug.log` (window/framebuffer size, GL viewport and 101 pixel zoom on every resize/`cwinscale`, first `glDrawPixels` sizes). 102 - Use make debug to run it in ddd, a graphical front end to GDB, mostly unused. 103