pcgeos: building the PC/GEOS desktop and SDK from source

A graphical operating system kept in assembly and C

bluewaysw/pcgeos is the source tree for PC/GEOS, a graphical operating system with its own development SDK. The repository description calls it the official home of the PC/GEOS operating system technology, and the README states that it is the place to build the SDK and the release version of the system, and to collaborate on further development. The primary language of the tree is Assembly, and the top level listing shows the shape of the system: Appl, DOSAppl, Driver, FontData, Include, Library, Loader, Tools, Installed and TechDocs. That layout is a system, not a library. There is a loader, a driver directory, font data, application directories for both native and DOS applications, and an Installed tree where the build products land. The people this serves are developers who want to read how a graphical environment is put together, modify its applications, or build the SDK themselves so they can write their own programs against it.

The build chain runs through WATCOM and a pmake tool built first

The C parts are compiled with WATCOM, and the build itself is driven by pmake, which is not a given but something you compile from the tree. The repository contains a Tools directory with a pmake/pmake subdirectory, and the README makes building that tool the first step of the whole procedure. The order matters. pmake is installed first so that the general SDK tools can then be built from Installed/Tools, and only after that can the PC/GEOS components themselves be assembled from Installed. The target environment is produced separately, by a perl script that assembles a product environment for the chosen platform. This is a staged bootstrap, closer to the way an operating system of that era was actually put together than to a modern package manager. The README also notes that the base of the tree is the source used to build Breadbox Ensemble 4.13, reduced by modules identified as critical with regard to the licence chosen for the repository, which is Apache-2.0.

Four environment variables decide where the build lands

Configuration is done through environment variables, and getting them wrong is the most common way to waste an afternoon here. WATCOM must point at the root of the unzipped toolchain, for instance C:\WATCOM-V2, and the binnt directory of that installation has to be on the system path. ROOT_DIR has to be the root of the checkout, and LOCAL_ROOT has to be a local working directory that may start empty but should sit under the pcgeos tree, so your own application work can live there too. A fourth variable, BASEBOX, selects the emulator backend from the separate pcgeos-basebox repository: the README describes setting it to basebox so the advanced emulator backend is used if that executable is on the path, and says the full path to the executable may be given instead. The path ordering also matters, because sed and perl must resolve to the right versions, and the README warns about the order of the path entries to avoid loading the wrong Perl.

From checkout to a booted desktop, step by step

The prerequisites are modest on Linux, where sed and perl are usually present already. On Windows the README asks for sed from the usr/bin directory of the official git distribution, or from Cygwin, and the Strawberry Perl distribution, with the note about ordering the path so the intended Perl is loaded first. Assuming the variables are set, the build runs in three pmake stages. First the build tool itself:

cd %ROOT_DIR%/Tools/pmake/pmake
wmake install

Then the remaining SDK tools:

cd %ROOT_DIR%/Installed/Tools
pmake install

And then every PC/GEOS component:

cd %ROOT_DIR%/Installed
pmake

The target environment comes last, from the perl script:

perl %ROOT_DIR%/Tools/build/product/bbxensem/Scripts/buildbbx.pl

That script asks a series of questions. The README lists the answers it expects: nt for the platform, y for the EC version, n because the build for Double-Byte Character Sets is not yet fully functional, y for the geodes, n for the VM files, and then a path to a gbuild folder inside your LOCAL_ROOT folder. The README also warns that several "Could not find file name in any of the source trees" messages are expected from the current version of the script, which saves you from chasing a warning that is part of normal operation.

Debug and release are two products, launched with target and target -n

The perl build step picks between two flavours of the system. The EC version is the debug build with stricter error checking, better suited for debugging, and the NC version is the release build, which is faster and corresponds to the actual release. They can be built at the same time into two different gbuild folders, with the EC path ending in gbuild.ec and the NC path ending in gbuild or gbuild.nc. Launching is done through a script in the checkout, and the default target is the EC debug build:

%ROOT_DIR%/bin/target

To start the NC release build instead, the README gives the command as target -n. The environment runs under dosbox, so dosbox has to be on the path, or the pcgeos-basebox emulator has to be installed and configured through the BASEBOX variable. In the EC build the swat debugger stops right after the first stage of the boot process, and at the "=>" prompt you can enter quit to detach it and run PC/GEOS standalone, or c to keep the debugger attached in the background, which is slower.

Per developer machine settings live in basebox_user.conf

The shared configuration file at %ROOT_DIR%/bin/basebox.conf is not the place for personal tweaks, and the README says so directly: if you want to change the target environment settings for yourself only, create a file called basebox_user.conf in your LOCAL_ROOT folder. Settings in that file overwrite those from basebox.conf. The example given in the README is a CPU cycle count:

[cpu]
cycles=55000

This separation matters more than it first appears. PC/GEOS runs inside an emulator, so the emulated machine has to be described in a file, and a single checked-in file would mean every contributor fights over the same CPU and memory settings. Keeping per developer overrides in LOCAL_ROOT, which the README asks you to keep under the pcgeos tree, also means your own application work and your machine profile stay together and stay out of version control.

What the repository does not give you

Several conveniences are simply absent. The toolchain is not bundled: you fetch a WATCOM snapshot separately, and the one the README calls currently tested is the 2020-12-01 build. Debugging on Linux needs the xdotools package installed, so that swat receives keyboard focus when it should, which is an extra dependency on the host and not on the emulated system. The documentation is described as work in progress, and the README points to a browsable version of it hosted at bluewaysw.github.io/pcgeos while the Markdown sources sit in the TechDocs folder. There is no packaged installer for the produced system in the top level listing, only the sources and the tools. There is also no short summary of which modules were dropped from the Breadbox Ensemble 4.13 base, beyond the statement that the reduction was made on licence grounds. The primary language of the tree, Assembly, is the real limit on who can contribute: the user interface, the drivers and the runtime are read and written at that level.

Editorial conclusion

pcgeos suits an engineer who wants to read, patch and run a graphical operating system, and who is prepared to install the WATCOM toolchain and learn the pmake build. It does not suit a team looking for a modern package to depend on, a hosted service, or a build that runs on an unmodified macOS or Linux image without extra tooling. Verify first that the WATCOM snapshot named in the instructions, 2020-12-01, still matches your compiler expectations, then check that BASEBOX resolves on your path and that the build answers nt/y/n/y/n still produce a target directory under LOCAL_ROOT. The licence field on the repository says Apache-2.0, and the last push was on 2026-10-20, with CI-latest release artifacts published on 2026-10-12.

Frequently asked questions

Official sources

1. bluewaysw/pcgeos on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases