A GNUstep front end for Executor

Five agents read both trees. Four findings changed the shape of the work; two of them reversed assumptions this project was carrying.

Subclass one C++ class. There are no required free functions and no global symbols to define beyond a single typedef.

Must implement

Everything else has a working default. Cursor, title, scrap, beep, palette and rootless region are all optional — and Qt, the reference implementation, overrides only the two cursor methods.

What you call into

// IEventListener — available as the protected member callbacks_
mouseButtonEvent(bool down, int h, int v);
mouseMoved(int h, int v);
keyboardEvent(bool down, unsigned char mkvkey);   // Mac virtual key code
suspendEvent();                                   // focus lost
resumeEvent(bool updateClipboard);                // focus gained
requestQuit();

All are safe to call from the GUI thread. They marshal internally: the event sink queues a std::function and fires a synthetic 68k interrupt, which the emulator thread services. The front end never touches Toolbox state directly.

The toolkit owns the main thread; the emulator runs on a worker. That is exactly the AppKit model, and the impedance match is the single best thing about this port.

Pixels

Two buffers, one image rep aliasing a buffer you own, no copy. The 1993 code invented this and the modern base class does the hard part for you.

A new directory, src/config/front-ends/gnustep/, mirroring how qt/ is organised one for one.

Build wiring

Three edits to existing files: add gnustep to the FRONT_ENDS cache list, add one add_subdirectory, and ship the new CMakeLists.txt. Everything downstream — the per-front-end executable, the target naming, the include path — is picked up automatically.

Three toolchain rules that are not optional

Each of these produces a failure that looks like something else — heap corruption, a mystery segfault, a link error about a symbol you never wrote. Getting them right up front costs nothing; getting them wrong costs days.

The mechanics below follow the existing pattern in the tree: set the language explicitly per source file rather than enabling it project-wide.

find_program(GNUSTEP_CONFIG gnustep-config)
if(GNUSTEP_CONFIG)
  execute_process(COMMAND ${GNUSTEP_CONFIG} --objc-flags OUTPUT_VARIABLE GS_OBJC_FLAGS
                  OUTPUT_STRIP_TRAILING_WHITESPACE)
  execute_process(COMMAND ${GNUSTEP_CONFIG} --gui-libs   OUTPUT_VARIABLE GS_GUI_LIBS
                  OUTPUT_STRIP_TRAILING_WHITESPACE)
  separate_arguments(GS_OBJC_FLAGS_LIST UNIX_COMMAND "${GS_OBJC_FLAGS}")
  separate_arguments(GS_GUI_LIBS_LIST   UNIX_COMMAND "${GS_GUI_LIBS}")

  add_library(front-end-gnustep
      default_vdriver.h gnustep.h gnustep.mm gnustepkeycodes.mm
      gnustep_mainthread.mm available_geometry.mm ../x/x_keycodes.cpp)

  set_source_files_properties(gnustep.mm gnustepkeycodes.mm gnustep_mainthread.mm
      available_geometry.mm PROPERTIES COMPILE_OPTIONS "-x;objective-c++")

  target_compile_options(front-end-gnustep PRIVATE ${GS_OBJC_FLAGS_LIST})
  # The version pin is the whole ballgame. See above.
  set_property(SOURCE gnustep.mm gnustepkeycodes.mm gnustep_ui.mm
    APPEND PROPERTY COMPILE_OPTIONS
      ${GS_OBJC_FLAGS_LIST}
      -fobjc-runtime=gnustep-2.2
      -fblocks -fexceptions -fobjc-exceptions -D_NATIVE_OBJC_EXCEPTIONS)

  target_include_directories(front-end-gnustep PUBLIC .)
  target_link_libraries(front-end-gnustep syn68k romlib ${GS_GUI_LIBS_LIST})
endif()

# Configure the whole project with:
#   cmake .. -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
#            -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld"

--objc-flags carries -MMD -MP, which fight CMake's own depfile handling — filter those two out and keep the rest. --gui-libs is a superset of the base and objc link flags, so one call covers the link side. Do not enable ARC; this codebase is manual retain/release throughout, though ARC is per-file so mixing would be legal if you ever wanted it.

Worth adding a hard failure in CMake if the discovered flags mention -fobjc-runtime= while the C++ compiler is not clang. That single check converts the most likely misconfiguration from a runtime segfault into a configure-time error message.

You get Mac windows floating over your desktop with no grey box around them. You do not get NSWindows the window manager can move independently.

Why per-window is a core rewrite, not a front end

The single-framebuffer assumption is load-bearing at four independent levels. Two of them cannot be removed without breaking guest applications.

The historical evidence agrees. ARDI wrote the NeXTSTEP front end with full AppKit available and complete control of their own source, and used one window. Their wishlist file got as far as "give some thought to rootless windows during the code restructuring." What shipped thirty years later is the shape mask.

Sound

GNUstep's NSSound plays complete, pre-existing files through loadable sink bundles. There is no PCM callback and no streaming-buffer API — nothing resembling SDL_AudioCallback. Executor synthesises audio on the fly from the guest's snd  resources at guest-chosen sample rates with hard latency requirements, and that cannot be expressed through the current interface.

It matters less than it sounds. Executor's sound goes through its own SoundDriver abstraction — a hunger model where the driver hands the core a buffer and a time window, the core fills it, the driver plays it. The backend is a swappable class of roughly 170 lines. Worth knowing: modern Executor is silent on every current front end anyway, since the only real driver in the tree belongs to the legacy SDL1 build, and the 1993 NeXTSTEP one was never implemented either — both its functions are empty bodies.

Because all three sit behind one interface, this is not a decision that has to be made now — and nothing else blocks on it, since the fake driver gives correct timing and silence.

Each of these cost someone a day in 1993, or will cost you one in 2026. They are ordered by when you will hit them.

1. The update deadlock. requestUpdate() is always called with the driver mutex held, and your draw path takes the same mutex. Marshal with waitUntilDone:NO. Blocking there hangs on the first frame, every time. Conversely setMode and the cursor methods are called without the mutex and may block.
2. The bitmap format flag. The exact equivalent of what updateBuffer() emits is NSAlphaFirstBitmapFormat | NSBitmapFormatThirtyTwoBitLittleEndian. That second constant arrived in gnustep-gui 0.25. Verify it exists in your tree before writing anything else — if it doesn't, the fallback is a swizzle loop costing a full-frame pass.
3. A wrong pixel format silently costs you 307,200 iterations per frame. GNUstep's context checks whether a bitmap rep is "compatible" and, for anything that isn't canonical 8-bits-per-channel interleaved, falls into a nested per-pixel loop calling accessor methods once per pixel. At 640×480 that is three hundred thousand iterations of near-Objective-C work every single frame, and nothing warns you. The 1993 code's 16-bit 4:4:4 format would land squarely in it. Use 8 bits per channel, 32 bits per pixel, device RGB. Executor's colour spec is fully parameterised, so this is a constants change.
4. The 2-bit grayscale path draws nothing at all. Cairo's backend rejects any bitmap whose colour space isn't device or calibrated RGB — it logs a line and returns. A silent no-op. That path exists only for 1990s NeXT mono hardware; delete it rather than porting it.
5. Call [view allocateGState]. The old code does this with the comment "since we will be repeatedly focused on." Without it, per-frame lockFocus is ruinous and you will misdiagnose it as the conversion being slow.
6. Target the X11/cairo backend, not Wayland. GNUstep's Wayland backend emits no NSFlagsChanged events at all, so command, shift and option are simply dead, and it zeroes the keycode for Enter and Delete.
7. Modifiers are keys, not flags. The modern core derives modifier state by testing the key map, so there is no flags path at all. You must send explicit down and up keyboardEvent calls for the modifier keys themselves.
8. Grab the keyboard aggressively. Return YES unconditionally from -performKeyEquivalent: while a guest application is running, or the host menu swallows ⌘Q, ⌘W and friends before the guest sees them.
9. Call disableCursorRects once, wholesale. AppKit's cursor rectangles will otherwise fight the emulator for the pointer continuously.
10. The XOR cursor. Mac cursors have an invert mode that alpha-mask cursors cannot express. The 1993 solution was dithering inverted regions to a 50% checkerboard with a per-row alternating pattern. Read that code before writing yours.
11. Fix resumeEvent while you're here. Qt hardcodes true, SDL2 hardcodes false, and both are wrong. The 1995 code computed it correctly from the pasteboard change count, which is what decides whether the guest needlessly reconverts the clipboard on every focus change.
12. Don't inherit the singleton-via-file-statics pattern. The old code apologises for it in its own source. Hold your view and window as members of the driver object.

Open: four libraries not yet reviewed

This review read Executor's two trees plus libs-gui and libs-back. Four more libraries were not read, and each could materially change a conclusion here — two of them the most expensive conclusions. Review these before committing to the architecture.

The Gershwin desktop sources are the other unread input, and they answer a question none of the above do: what the desktop already provides, so the front end integrates with its window manager and menu bar rather than duplicating them.

What nobody could determine

Stated plainly, because a plan that hides its unknowns is worse than one that names them. None of the following was verified, and no code in this review was compiled or executed:

• The literal output of gnustep-config --objc-flags on a current install. The flags above are derived from gnustep-make's own makefiles, not observed.
• Whether distribution -dev packages install the internal header that gates the raw-Xlib escape hatch.
• Any GNUstep drawing benchmark newer than 2015.
• Whether recent binutils fixed the GNU ld problem, or whether lld remains mandatory.
• First-hand reports for window levels under KWin, Mutter or i3 — the always-above gap is inferred from source only.

The licensing story is unusually clean for retrocomputing: none of this requires an Apple ROM or a copy of Mac OS, which is the constraint that blocks Basilisk II, Mini vMac and the QEMU m68k path from ever shipping in an image.