DSCF

.co.uk

PC32

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

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