Repository navigation
Expand file tree
/
Copy pathgnustep-executor-port-plan.html
More file actions
993 lines (896 loc) · 63.5 KB
/
Copy pathgnustep-executor-port-plan.html
File metadata and controls
993 lines (896 loc) · 63.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Executor on GNUstep — Front-End Porting Plan</title>
<style>
:root{
/* The NeXT MegaPixel display had four levels. So does this page. */
--k:#000000;
--dk:#555555;
--gy:#aaaaaa;
--wh:#ffffff;
--paper:#f4f4f2;
--paper2:#e9e9e6;
--desk:#5f6062;
--ok:#2c6141; --ok-bg:#dae8de;
--warn:#7d6118; --warn-bg:#ece5cf;
--stop:#8a2f2f; --stop-bg:#eddcdc;
--sans:Helvetica,"Helvetica Neue","Nimbus Sans","Liberation Sans",Arial,sans-serif;
--mono:"DejaVu Sans Mono","Nimbus Mono PS","Liberation Mono",Menlo,Consolas,monospace;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{
margin:0; padding:34px 20px 90px;
background:var(--desk);
color:var(--k);
font:14px/1.6 var(--sans);
}
/* ---------- bevels ---------- */
.raised{box-shadow:inset 1px 1px 0 var(--wh), inset -1px -1px 0 var(--dk)}
.sunken{box-shadow:inset 1px 1px 0 var(--dk), inset -1px -1px 0 var(--wh)}
/* ---------- panel ---------- */
.wrap{max-width:1000px; margin:0 auto; display:flex; flex-direction:column; gap:22px}
.panel{background:var(--gy); border:1px solid var(--k); box-shadow:3px 3px 0 rgba(0,0,0,.4)}
.panel__bar{
display:flex; align-items:center; gap:9px; padding:5px 7px;
background:var(--gy); border-bottom:1px solid var(--k);
box-shadow:inset 1px 1px 0 var(--wh), inset -1px -1px 0 var(--dk);
}
.panel__btn{
width:16px; height:16px; flex:none; background:var(--gy); border:1px solid var(--k);
box-shadow:inset 1px 1px 0 var(--wh), inset -1px -1px 0 var(--dk);
display:grid; place-items:center; font:10px/1 var(--sans); color:var(--dk);
}
.panel__title{
flex:1 1 auto; text-align:center; font:700 13px/1.2 var(--sans);
letter-spacing:.02em; white-space:nowrap; overflow:hidden; text-overflow:ellipsis;
}
.panel__body{background:var(--paper); border-top:1px solid var(--wh); padding:22px 24px 26px}
/* ---------- masthead ---------- */
.mast .panel__body{padding:28px 26px 26px}
.mast h1{font:700 30px/1.14 var(--sans); letter-spacing:-.02em; margin:0 0 8px; text-wrap:balance}
.mast .eyebrow{
font:700 10.5px/1 var(--sans); letter-spacing:.2em; text-transform:uppercase;
color:var(--dk); margin:0 0 14px;
}
.mast .verdict{font-size:16px; line-height:1.55; max-width:64ch; margin:0 0 16px}
.mast .verdict b{background:#d8d8cf; padding:0 3px}
/* ---------- typography ---------- */
h2{font:700 12px/1 var(--sans); letter-spacing:.16em; text-transform:uppercase;
margin:30px 0 12px; padding-bottom:6px; border-bottom:2px solid var(--k)}
h2:first-child{margin-top:0}
h3{font:700 15px/1.3 var(--sans); margin:22px 0 7px}
p{margin:0 0 12px; max-width:70ch}
ul,ol{margin:0 0 13px; padding-left:20px; max-width:70ch}
li{margin:0 0 6px}
code{font-family:var(--mono); font-size:.87em; background:var(--paper2); padding:1px 4px; border:1px solid #ccccc6}
a{color:var(--k)}
.lede{font-size:15px; max-width:66ch}
/* ---------- stat strip ---------- */
.stats{display:grid; grid-template-columns:repeat(auto-fit,minmax(150px,1fr)); gap:2px; background:var(--k); border:1px solid var(--k); margin:0 0 18px}
.stat{background:var(--paper2); padding:12px 14px}
.stat b{display:block; font:700 25px/1.1 var(--sans); letter-spacing:-.02em; font-variant-numeric:tabular-nums}
.stat span{display:block; font:700 9.5px/1.35 var(--sans); letter-spacing:.11em; text-transform:uppercase; color:var(--dk); margin-top:4px}
/* ---------- tables ---------- */
.tw{overflow-x:auto; border:1px solid var(--k); margin:0 0 16px; background:var(--wh)}
table{border-collapse:collapse; width:100%; min-width:580px; font-size:13px}
th,td{border:1px solid #c4c4bd; padding:8px 10px; text-align:left; vertical-align:top}
thead th{background:var(--gy); border-color:var(--k); font:700 10.5px/1.3 var(--sans);
letter-spacing:.09em; text-transform:uppercase; box-shadow:inset 1px 1px 0 var(--wh)}
tbody tr:nth-child(even) td{background:var(--paper2)}
td.n{font-family:var(--mono); font-size:11.5px; text-align:right; font-variant-numeric:tabular-nums; white-space:nowrap}
td code{background:transparent; border:0; padding:0}
/* ---------- chips ---------- */
.chip{display:inline-block; border:1px solid var(--k); padding:1px 7px; background:var(--gy);
font:700 10px/1.7 var(--sans); letter-spacing:.07em; text-transform:uppercase; white-space:nowrap;
box-shadow:inset 1px 1px 0 var(--wh), inset -1px -1px 0 var(--dk)}
.chip--ok{background:var(--ok-bg); color:var(--ok)}
.chip--warn{background:var(--warn-bg); color:var(--warn)}
.chip--stop{background:var(--stop-bg); color:var(--stop)}
/* ---------- notes ---------- */
.note{border:1px solid var(--k); background:var(--wh); padding:14px 16px; margin:0 0 16px;
box-shadow:inset 1px 1px 0 var(--wh), inset -1px -1px 0 #ccccc6}
.note h3{margin:0 0 6px; font-size:14px}
.note p:last-child,.note ul:last-child{margin-bottom:0}
.note--ok{background:var(--ok-bg)}
.note--warn{background:var(--warn-bg)}
.note--stop{background:var(--stop-bg)}
.note--trap{background:#f0e4e4; border-width:2px}
/* ---------- code blocks ---------- */
pre{margin:0 0 16px; padding:13px 15px; background:#1c1c1c; color:#e8e8e4; overflow-x:auto;
font:12px/1.6 var(--mono); border:1px solid var(--k)}
pre b{color:#ffd479; font-weight:400}
pre i{color:#9a9a92; font-style:normal}
/* ---------- figures ---------- */
figure{margin:2px 0 18px}
.fig{border:1px solid var(--k); background:var(--wh); padding:15px; overflow-x:auto}
.fig svg{display:block; min-width:540px; width:100%; height:auto}
figcaption{font:700 10px/1.5 var(--sans); letter-spacing:.1em; text-transform:uppercase; color:var(--dk); margin-top:8px}
svg text{font-family:var(--sans)}
svg .t{font-size:11.5px}
svg .s{font-size:9.5px; fill:var(--dk)}
svg .m{font-family:var(--mono); font-size:10px}
svg .h{font-size:10px; font-weight:700; letter-spacing:.09em; text-transform:uppercase}
/* ---------- two-up ---------- */
.two{display:grid; grid-template-columns:repeat(auto-fit,minmax(292px,1fr)); gap:16px; margin-bottom:16px}
.card{border:1px solid var(--k); background:var(--wh); padding:14px 16px}
.card h3{margin-top:0}
.card p:last-child,.card ul:last-child{margin-bottom:0}
.card--keep{background:#e6ede6}
.card--drop{background:#efe6e6}
/* ---------- trap list ---------- */
.traps{list-style:none; padding:0; margin:0; counter-reset:trap; max-width:none}
.traps li{
counter-increment:trap; display:grid; grid-template-columns:30px 1fr; gap:12px;
border:1px solid var(--k); background:var(--wh); padding:12px 14px; margin:0 0 8px; max-width:none;
}
.traps li::before{
content:counter(trap,decimal-leading-zero); font:700 13px/1.1 var(--mono);
color:var(--dk); padding-top:2px;
}
.traps b{display:block; margin-bottom:3px}
/* ---------- footer ---------- */
footer{max-width:1000px; margin:26px auto 0; padding:0 4px; color:#d8d8d4;
font:11px/1.7 var(--sans); letter-spacing:.04em}
footer a{color:#fff}
@media (max-width:640px){
body{padding:14px 10px 60px}
.panel__body{padding:16px 15px 18px}
.mast h1{font-size:23px}
}
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
@media print{body{background:#fff;padding:0}.panel{box-shadow:none;break-inside:avoid}}
</style>
</head>
<body>
<div class="wrap">
<!-- ============================ MASTHEAD ============================ -->
<section class="panel mast">
<div class="panel__bar">
<span class="panel__btn" aria-hidden="true">□</span>
<span class="panel__title">Executor.app — Porting Plan</span>
<span class="panel__btn" aria-hidden="true">×</span>
</div>
<div class="panel__body">
<p class="eyebrow">Code review findings · 27 July 2026</p>
<h1>A GNUstep front end for Executor</h1>
<p class="verdict">Give ARDI's Macintosh Toolbox reimplementation a native AppKit front end, so classic Mac
applications run as first-class windows on Gershwin. <b>This is a new component of roughly 1,000–2,000 lines,
not a port of the 8,453-line 1993 NeXTSTEP front end.</b> That old code is worth reading for its hard-won Mac
semantics and worth almost nothing as source.</p>
<div class="stats">
<div class="stat"><b>4</b><span>pure virtuals to implement</span></div>
<div class="stat"><b>~700</b><span>lines for the driver</span></div>
<div class="stat"><b>+300–600</b><span>lines of UI, built in code</span></div>
<div class="stat"><b>8 d</b><span>to milestone one</span></div>
</div>
<div class="note note--warn">
<h3>Read this before scoping anything</h3>
<p>One question in this plan is genuinely unanswered, and it is not a detail: <b>no emulator of any kind has ever
used GNUstep AppKit for framebuffer display.</b> Previous, Basilisk II and SheepShaver all use SDL, Cocoa, Qt
or GTK. The blit path is unproven, GNUstep's backend has no shared-memory X extension anywhere in it, and the only
published drawing benchmark dates from 2015. <b>Spike that before writing anything else</b> — see step 0.</p>
</div>
<p>Fork: <a href="https://github.com/pkgdemon/executor">github.com/pkgdemon/executor</a> (Cliff Matthews' 2008
release, MIT, containing the NeXTSTEP front end). Build target is autc04's modern tree — C++17, CMake, and
seventeen years of divergence. The two are read together: one for design, one for the contract.</p>
</div>
</section>
<!-- ============================ FINDINGS ============================ -->
<section class="panel">
<div class="panel__bar">
<span class="panel__btn" aria-hidden="true">□</span>
<span class="panel__title">1 — What the review found</span>
<span class="panel__btn" aria-hidden="true">×</span>
</div>
<div class="panel__body">
<p class="lede">Five agents read both trees. Four findings changed the shape of the work; two of them reversed
assumptions this project was carrying.</p>
<div class="note note--ok">
<h3>Modern front ends are tiny</h3>
<p>The host-integration contract is far smaller than the 1993 code suggests, because that code carried an entire
application around with it — registration nags, serial numbers, a splash screen, ARDI's phone number in five
separate string constants.</p>
<div class="tw">
<table>
<thead><tr><th style="width:24%">Front end</th><th style="width:16%">Lines</th><th>Note</th></tr></thead>
<tbody>
<tr><td><code>headless</code></td><td class="n">31</td><td>Proves the true minimum surface.</td></tr>
<tr><td><code>sdl2</code></td><td class="n">472</td><td>—</td></tr>
<tr><td><code>qt</code></td><td class="n">599</td><td><b>The template.</b> The only high-level-toolkit front end, and the closest structural analogue to AppKit.</td></tr>
<tr><td><code>wayland</code></td><td class="n">690</td><td>—</td></tr>
<tr><td><code>x</code></td><td class="n">1,495</td><td>Source of the reusable keycode table.</td></tr>
<tr><td><i>old <code>nextstep</code></i></td><td class="n">8,453</td><td>Design reference only.</td></tr>
</tbody>
</table>
</div>
</div>
<div class="note note--stop">
<h3>Reversal: per-Mac-window <code>NSWindow</code>s are not possible</h3>
<p>The appealing idea — make each Mac window a real AppKit window and let Gershwin's window manager handle
them natively — does not survive contact with the code. <b>The guest renders every Mac window into one flat
framebuffer, and Executor's Window Manager knows nothing about host windows.</b> A grep for <code>rootless</code>
across the entire 2008 tree returns zero hits, and <code>MacViewClass.m:39-45</code> apologises in its own comments
for being a hard singleton.</p>
<p>What <em>is</em> available is better than nothing and worse than the fantasy — see §5.</p>
</div>
<div class="note note--ok">
<h3>Reversal, the other way: rootless already exists upstream</h3>
<p>The modern tree has first-class rootless support that the 1993 code never had:
<code>Framebuffer::rootless</code> (<code>vdriver.h:55</code>), <code>setRootlessRegion(RgnHandle)</code>
(<code>:131</code>), <code>isRootless()</code> (<code>:149</code>), plus <code>src/wind/windRootless.cpp</code>.
Qt turns it on at <code>qt.cpp:213</code> and shapes its window from the region at <code>:244-249</code>. Seamless
windowing is not research. It is a feature you switch on.</p>
</div>
<div class="note note--warn">
<h3>The 1997 OpenStep branch is not a head start</h3>
<p>Every file in the old front end is dual-compiled <code>#ifdef OPENSTEP</code>. The NEXTSTEP branch is finished,
shipped code. The OpenStep branch is an abandoned port: tracking rects dead, keyboard translation gutted, dead keys
dropped, and at <code>MacViewClass.m:2606</code> a declaration taking <code>NSString</code> <em>by value</em>, which
cannot compile. Read the NEXTSTEP branch for design; read the OpenStep branch as a list of what breaks.</p>
</div>
</div>
</section>
<!-- ============================ CONTRACT ============================ -->
<section class="panel">
<div class="panel__bar">
<span class="panel__btn" aria-hidden="true">□</span>
<span class="panel__title">2 — The contract</span>
<span class="panel__btn" aria-hidden="true">×</span>
</div>
<div class="panel__body">
<p class="lede">Subclass one C++ class. There are no required free functions and no global symbols to define beyond a
single typedef.</p>
<h2>Must implement</h2>
<div class="tw">
<table>
<thead><tr><th style="width:40%">Member</th><th style="width:16%">Called on</th><th>Constraint</th></tr></thead>
<tbody>
<tr><td><code>runEventLoop()</code></td><td>main thread</td><td>Blocks for the whole session. In AppKit this is <code>[NSApp run]</code> — roughly three lines.</td></tr>
<tr><td><code>endEventLoop()</code></td><td>emulator thread</td><td>Must be async and thread-safe. <code>[NSApp stop:]</code> <em>plus</em> a posted dummy event, or it won't take effect until the next event arrives.</td></tr>
<tr><td><code>setMode(w,h,bpp,gray)</code></td><td>emulator thread</td><td>Allocates the framebuffer. May block on the main thread; must not require the run loop to be spinning already.</td></tr>
<tr><td><code>requestUpdate()</code></td><td>emulator thread</td><td><b>Called with the driver mutex held.</b> Must never block. See trap 01.</td></tr>
<tr><td><code>ctor(IEventListener*, int& argc, char**)</code></td><td>main thread</td><td>Runs before the emulator thread exists.</td></tr>
<tr><td><code>default_vdriver.h</code></td><td>—</td><td>Three lines: <code>using DefaultVDriver = GNUstepVideoDriver;</code> Included by <code>main.cpp</code>, which is compiled as <em>plain C++</em> — so this header and its includes must be Objective-C-free.</td></tr>
</tbody>
</table>
</div>
<p>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.</p>
<h2>What you call into</h2>
<pre><i>// IEventListener — available as the protected member callbacks_</i>
mouseButtonEvent(bool down, int h, int v);
mouseMoved(int h, int v);
keyboardEvent(bool down, unsigned char <b>mkvkey</b>); <i>// Mac virtual key code</i>
suspendEvent(); <i>// focus lost</i>
resumeEvent(bool updateClipboard); <i>// focus gained</i>
requestQuit();</pre>
<p>All are safe to call from the GUI thread. They marshal internally: the event sink queues a
<code>std::function</code> and fires a synthetic 68k interrupt, which the emulator thread services. The front end
never touches Toolbox state directly.</p>
</div>
</section>
<!-- ============================ THREADING ============================ -->
<section class="panel">
<div class="panel__bar">
<span class="panel__btn" aria-hidden="true">□</span>
<span class="panel__title">3 — Threading and the pixel path</span>
<span class="panel__btn" aria-hidden="true">×</span>
</div>
<div class="panel__body">
<p class="lede">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.</p>
<figure>
<div class="fig">
<svg viewBox="0 0 900 300" role="img" aria-label="Threading model: main thread runs NSApp, emulator thread runs the guest, worker pool converts pixels" shape-rendering="crispEdges">
<defs><marker id="a1" markerWidth="9" markerHeight="9" refX="8" refY="4.5" orient="auto"><path d="M0 1 L8 4.5 L0 8 Z" fill="#000"/></marker></defs>
<text x="10" y="18" class="h">Main thread — AppKit owns it</text>
<rect x="10" y="26" width="400" height="86" fill="#e9e9e6" stroke="#000"/>
<rect x="22" y="38" width="176" height="28" fill="#fff" stroke="#000"/>
<text x="110" y="56" class="t" text-anchor="middle">[NSApp run]</text>
<rect x="22" y="74" width="176" height="28" fill="#fff" stroke="#000"/>
<text x="110" y="92" class="t" text-anchor="middle">-drawRect:</text>
<rect x="214" y="38" width="184" height="64" fill="#fff" stroke="#000"/>
<text x="306" y="58" class="t" text-anchor="middle">All NSView / NSWindow</text>
<text x="306" y="74" class="t" text-anchor="middle">/ NSCursor calls</text>
<text x="306" y="92" class="s" text-anchor="middle">no exceptions</text>
<text x="490" y="18" class="h">Emulator thread</text>
<rect x="490" y="26" width="400" height="86" fill="#e9e9e6" stroke="#000"/>
<rect x="502" y="38" width="180" height="64" fill="#fff" stroke="#000"/>
<text x="592" y="58" class="t" text-anchor="middle">68k guest execution</text>
<text x="592" y="76" class="t" text-anchor="middle">Toolbox + QuickDraw</text>
<rect x="698" y="38" width="180" height="64" fill="#fff" stroke="#000"/>
<text x="788" y="52" class="m" text-anchor="middle">setMode setColors</text>
<text x="788" y="68" class="m" text-anchor="middle">setCursor updateScreen</text>
<text x="788" y="86" class="s" text-anchor="middle">called from here</text>
<path d="M410 60 H486" stroke="#000" fill="none" marker-end="url(#a1)"/>
<path d="M486 92 H414" stroke="#000" fill="none" marker-end="url(#a1)"/>
<text x="448" y="52" class="s" text-anchor="middle">callbacks_</text>
<text x="448" y="112" class="s" text-anchor="middle">marshal back</text>
<text x="10" y="146" class="h">Worker pool — owned by the base class</text>
<rect x="10" y="154" width="880" height="52" fill="#e9e9e6" stroke="#000"/>
<text x="24" y="176" class="t">updateBuffer() — depth, endian and palette conversion, fanned across hardware_concurrency()-2 threads</text>
<text x="24" y="194" class="s">Must be called with the mutex RELEASED. It runs long.</text>
<rect x="10" y="228" width="880" height="60" fill="#f0e4e4" stroke="#000" stroke-width="2"/>
<text x="24" y="250" class="h">The deadlock</text>
<text x="24" y="268" class="t">requestUpdate() is always invoked with mutex_ already locked, and your draw path takes that same mutex.</text>
<text x="24" y="283" class="t">Marshal it with waitUntilDone:NO. A blocking marshal here hangs instantly, every time.</text>
</svg>
</div>
<figcaption>Fig. 1 — Thread ownership</figcaption>
</figure>
<h2>Pixels</h2>
<p>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.</p>
<figure>
<div class="fig">
<svg viewBox="0 0 900 190" role="img" aria-label="Pixel pipeline from guest framebuffer through updateBuffer to NSBitmapImageRep" shape-rendering="crispEdges">
<defs><marker id="a2" markerWidth="9" markerHeight="9" refX="8" refY="4.5" orient="auto"><path d="M0 1 L8 4.5 L0 8 Z" fill="#000"/></marker></defs>
<g fill="#fff" stroke="#000">
<rect x="10" y="44" width="176" height="70"/>
<rect x="240" y="44" width="176" height="70"/>
<rect x="470" y="44" width="176" height="70"/>
<rect x="700" y="44" width="190" height="70"/>
</g>
<g class="t" text-anchor="middle">
<text x="98" y="66">Guest framebuffer</text>
<text x="330" y="66">updateBuffer()</text>
<text x="558" y="66">Staging buffer</text>
<text x="795" y="66">NSBitmapImageRep</text>
</g>
<g class="s" text-anchor="middle">
<text x="98" y="84">1/2/4/8 indexed, MSB-first</text>
<text x="98" y="98">16/32 bpp big-endian Mac</text>
<text x="330" y="84">depth + endian + palette</text>
<text x="330" y="98">on the worker pool</text>
<text x="558" y="84">uint32_t 0xAARRGGBB</text>
<text x="558" y="98">host order, you own it</text>
<text x="795" y="84">wraps the buffer, no copy</text>
<text x="795" y="98">-drawInRect:fromRect:</text>
</g>
<g stroke="#000" fill="none" marker-end="url(#a2)">
<path d="M186 79 H236"/><path d="M416 79 H466"/><path d="M646 79 H696"/>
</g>
<text x="10" y="26" class="h">The framebuffer is big-endian Mac format. Never hand it to AppKit directly.</text>
<text x="10" y="150" class="s">Dirty rects are capped at 5 and auto-merged into unions when they overlap. Palette changes dirty the whole screen — correct, since a CLUT change alters every pixel's meaning.</text>
<text x="10" y="170" class="s">Qt performs zero conversion of its own: QImage::Format_RGB32 is bit-identical to what updateBuffer emits. The AppKit equivalent needs one specific format flag — see trap 02.</text>
</svg>
</div>
<figcaption>Fig. 2 — Pixel pipeline</figcaption>
</figure>
</div>
</section>
<!-- ============================ FILES ============================ -->
<section class="panel">
<div class="panel__bar">
<span class="panel__btn" aria-hidden="true">□</span>
<span class="panel__title">4 — Files to write</span>
<span class="panel__btn" aria-hidden="true">×</span>
</div>
<div class="panel__body">
<p class="lede">A new directory, <code>src/config/front-ends/gnustep/</code>, mirroring how <code>qt/</code> is
organised one for one.</p>
<div class="tw">
<table>
<thead><tr><th style="width:25%">File</th><th style="width:10%">LOC</th><th>Purpose</th></tr></thead>
<tbody>
<tr><td><code>gnustep.mm</code></td><td class="n">380–450</td><td>The driver. <code>ExecutorView : NSView</code>, a borderless <code>ExecutorWindow : NSWindow</code>, the app delegate, and every <code>VideoDriver</code> override.</td></tr>
<tr><td><code>gnustepkeycodes.mm</code></td><td class="n">120–160</td><td>Fallback unichar→MKV map, plus modifier decoding for <code>-flagsChanged:</code>. AppKit does not deliver modifiers as key events; Qt sidestepped this and you cannot.</td></tr>
<tr><td><code>gnustep_ui.mm</code></td><td class="n">300–600</td><td><b>The menu and windows, built in code.</b> There is no nib — see below. Qt needs none of this, so it is pure delta against the reference implementation.</td></tr>
<tr><td><code>gnustep_mainthread.mm</code></td><td class="n">50–70</td><td><code>runOnMainThread(fn, wait)</code> over <code>-performSelectorOnMainThread:</code>. The one file with no Qt counterpart — Qt got this free from its framework.</td></tr>
<tr><td><code>available_geometry.mm</code></td><td class="n">40–55</td><td>Screen rects from <code>[NSScreen screens]</code>, bottom-left to top-left. Simpler than Qt's, which carries X11 multi-monitor workarounds.</td></tr>
<tr><td><code>gnustep.h</code></td><td class="n">40–55</td><td><b>Pure C++, no Objective-C.</b> Objective-C types hidden behind <code>#ifdef __OBJC__ @class … #else typedef struct objc_object …</code></td></tr>
<tr><td><code>CMakeLists.txt</code></td><td class="n">35–45</td><td>Locate GNUstep, apply <code>-x objective-c++</code> to the <code>.mm</code> files, link.</td></tr>
<tr><td><code>default_vdriver.h</code></td><td class="n">3</td><td>The typedef.</td></tr>
<tr><td><i><code>../x/x_keycodes.cpp</code></i></td><td class="n">0</td><td><b>Reused verbatim.</b> Listed as a source, exactly as Qt's CMakeLists already does.</td></tr>
</tbody>
</table>
</div>
<div class="note note--stop">
<h3>There is no nib, and there cannot be one</h3>
<p>Every interface file in the 1993 tree is <b>NeXT <code>typedstream</code> version 4</b> — the
pre-keyed-archiving format. Gorm cannot open them. GNUstep's model loader dispatches by signature to Gorm, keyed
<code>.nib</code>, <code>.xib</code> and <code>.gmodel</code> handlers; there is no typedstream path anywhere, so
loading them at runtime fails too. The conversion tools are dead ends: <code>nib2gmodel</code> was last touched in
2008 and requires Apple or NeXT libraries; <code>nib2xib</code> is maintained but runs only on OPENSTEP 4.2.</p>
<p><b>It costs almost nothing, because there is almost nothing in them.</b> The live UI is one menu, one window with
the framebuffer view, one info panel, and four implemented actions. Of seventeen actions the nibs declare, thirteen
are dead. <code>MacViewClass</code> declares <em>no instance variables at all</em>, so all seven outlets its
metadata references are stale. One declared class has no source file anywhere in the tree. The rest is ARDI-era
registration and serial-number UI whose backing code is gone — you would be converting dead weight in order to
delete it.</p>
<p>Build the UI programmatically. That is the 300–600 line file above, and it also lets you delete the entire
outlet layer — roughly 25 globals the old code copied out of the nib so plain C could reach them.</p>
</div>
<h2>Build wiring</h2>
<p>Three edits to existing files: add <code>gnustep</code> to the <code>FRONT_ENDS</code> cache list, add one
<code>add_subdirectory</code>, and ship the new <code>CMakeLists.txt</code>. Everything downstream — the
per-front-end executable, the target naming, the include path — is picked up automatically.</p>
<h2 style="border-bottom-width:2px">Three toolchain rules that are not optional</h2>
<p>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.</p>
<div class="two">
<div class="card card--drop">
<h3>Clang for the whole project</h3>
<p>GNUstep's runtime is libobjc2, and <b>GCC has no <code>-fobjc-runtime=</code> flag at all</b>. gnustep-make's
own configure forces <code>CC=clang</code>. Since the <code>.mm</code> files ride
<code>CMAKE_CXX_COMPILER</code>, that means the entire project must be clang — not just the shim.</p>
</div>
<div class="card card--drop">
<h3>Never <code>enable_language(OBJCXX)</code></h3>
<p>CMake's OBJCXX detection prefers <code>clang++</code>, while its CXX detection resolves to <code>g++</code>.
On a box with both, you get clang++ for one <code>.mm</code> and g++ for four hundred <code>.cpp</code> files
— <b>a split C++ ABI across exactly the boundary the front end straddles</b>, since that translation unit
consumes <code>vdriver.h</code> with <code>shared_ptr</code>, <code>function</code> and <code>string</code> in it.
Let <code>.mm</code> ride the CXX compiler and set the language per source file.</p>
</div>
<div class="card card--drop">
<h3><code>-fuse-ld=lld</code></h3>
<p>The v2 Objective-C ABI depends on section-boundary symbols that GNU ld mishandles; the classic symptom is
<code>cannot locate symbol __start___objc_selectors</code>. gnustep-make warns about this itself and admits it
has no accurate test. gold is deprecated upstream, so lld is the answer.</p>
</div>
</div>
<div class="note note--trap">
<h3>The footgun that will actually get you</h3>
<p>Clang's default Objective-C runtime on Linux is <b>not</b> GNUstep 2.x — a bare
<code>-fobjc-runtime=gnustep</code> means <b>1.6</b>. Compile a <code>.mm</code> without pinning the version and
clang emits the wrong personality function, after which <b>catching a <code>std::exception</code> segfaults</b>.
It was filed against LLVM and closed as invalid, the answer being "specify the runtime." CMake will cheerfully
compile Objective-C++ with no Objective-C flags whatsoever and hand you crashes that read as heap corruption.</p>
<p>Pin <code>-fobjc-runtime=gnustep-2.2</code> per source file. Not 2.0 — they are ABI-identical, but 2.2
unlocks compiler fast paths, and it is what gnustep-make defaults to. Requires clang 18 or newer.</p>
<p>Two related corrections to widely-repeated advice: <b>there is no <code>-lobjcxx</code> any more</b> — it
was folded into <code>libobjc.so</code> in 2017, though libobjc2's own <code>INSTALL</code> file still describes it.
And Objective-C++ exception interop is genuinely regression-tested in both directions across libstdc++ and libc++,
so it works — provided the runtime flag is right.</p>
</div>
<p>The mechanics below follow the existing pattern in the tree: set the language explicitly per source file rather
than enabling it project-wide.</p>
<pre>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})
<i># The version pin is the whole ballgame. See above.</i>
set_property(SOURCE gnustep.mm gnustepkeycodes.mm gnustep_ui.mm
APPEND PROPERTY COMPILE_OPTIONS
${GS_OBJC_FLAGS_LIST}
<b>-fobjc-runtime=gnustep-2.2</b>
-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()
<i># Configure the whole project with:</i>
<i># cmake .. -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \</i>
<i># -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld"</i></pre>
<p><code>--objc-flags</code> carries <code>-MMD -MP</code>, which fight CMake's own depfile handling — filter
those two out and keep the rest. <code>--gui-libs</code> 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.</p>
<p>Worth adding a hard failure in CMake if the discovered flags mention <code>-fobjc-runtime=</code> 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.</p>
</div>
</section>
<!-- ============================ ROOTLESS ============================ -->
<section class="panel">
<div class="panel__bar">
<span class="panel__btn" aria-hidden="true">□</span>
<span class="panel__title">5 — Rootless, honestly</span>
<span class="panel__btn" aria-hidden="true">×</span>
</div>
<div class="panel__body">
<p class="lede">You get Mac windows floating over your desktop with no grey box around them. You do not get
<code>NSWindow</code>s the window manager can move independently.</p>
<figure>
<div class="fig">
<svg viewBox="0 0 900 230" role="img" aria-label="Comparison of the fantasy per-window model against the real shaped-region model" shape-rendering="crispEdges">
<text x="10" y="18" class="h">The fantasy — not possible</text>
<rect x="10" y="26" width="420" height="150" fill="#efe6e6" stroke="#000"/>
<g fill="#fff" stroke="#000">
<rect x="40" y="52" width="150" height="60"/><rect x="120" y="86" width="150" height="60"/><rect x="230" y="60" width="150" height="60"/>
</g>
<text x="115" y="74" class="s">NSWindow</text><text x="195" y="108" class="s">NSWindow</text><text x="305" y="82" class="s">NSWindow</text>
<text x="24" y="168" class="s">Each Mac window an independent host window. Executor's Window</text>
<path d="M60 150 l40 26 M100 150 l-40 26" stroke="#8a2f2f" stroke-width="2" fill="none"/>
<text x="470" y="18" class="h">The reality — and it looks the same</text>
<rect x="470" y="26" width="420" height="150" fill="#dae8de" stroke="#000"/>
<rect x="486" y="38" width="388" height="126" fill="none" stroke="#555" stroke-dasharray="4 3"/>
<g fill="#fff" stroke="#000">
<rect x="500" y="52" width="150" height="60"/><rect x="580" y="86" width="150" height="60"/><rect x="690" y="60" width="150" height="60"/>
</g>
<text x="575" y="74" class="s">shaped region</text><text x="655" y="108" class="s">shaped region</text><text x="765" y="82" class="s">shaped region</text>
<text x="492" y="34" class="s">one transparent NSWindow, masked</text>
<text x="24" y="184" class="s">Manager has no concept of host windows and never will.</text>
<text x="24" y="204" class="t">Everything the guest draws lands in one flat framebuffer. That is a</text>
<text x="24" y="220" class="t">structural fact of Executor, not an oversight.</text>
<text x="484" y="196" class="t">Executor computes the region covering all Mac windows and hands it</text>
<text x="484" y="212" class="t">to you. You mask one full-screen transparent window with it. Visually</text>
<text x="484" y="228" class="t">identical; architecturally one window.</text>
</svg>
</div>
<figcaption>Fig. 3 — What rootless actually means</figcaption>
</figure>
<div class="note note--stop">
<h3>Executor's own documentation is wrong about this</h3>
<p>The README advertises "emulated windows are part of your desktop," and the subsystem docs state that in rootless
mode "windows are not drawn onto the emulator framebuffer" but are instead "delegated to the host compositor."
<b>The code flatly contradicts both.</b> The rootless path unions every visible window's structure region, plus the
menu bar, into <em>one</em> region and makes <em>one</em> call. Windows are still drawn into the framebuffer; the
region only selects which spans get copied and which are left transparent.</p>
<p>This matters beyond pedantry. Anyone scoping this project from the documentation would believe per-window host
integration is already half-built. <b>Settle the expectation in writing before any code is committed</b> —
and consider correcting those two doc files as a first, trivially reviewable pull request.</p>
</div>
<h2>Why per-window is a core rewrite, not a front end</h2>
<p>The single-framebuffer assumption is load-bearing at four independent levels. Two of them cannot be removed
without breaking guest applications.</p>
<div class="tw">
<table>
<thead><tr><th style="width:26%">Level</th><th>What it means</th></tr></thead>
<tbody>
<tr><td><b>Every port shares one bitmap</b></td><td>Each window's <code>GrafPort</code> points at the same screen bitmap. Windows draw at absolute screen coordinates, clipped by a visible region. They have no independent backing surface — which is faithful, because the real Macintosh worked this way too.</td></tr>
<tr><td><b>The framebuffer lives in the guest's address space</b></td><td>It is mapped into the 68k memory map and published as low-memory globals. <b>Guest code writes to screen memory directly</b>, and there is an entire subsystem — a periodic per-strip checksummer — that exists solely to notice when applications bypass QuickDraw and do exactly this. Those writes address screen coordinates. There is no general way to route them into per-window surfaces.</td></tr>
<tr><td><b>Window chrome can be guest code</b></td><td>Frames are drawn by the Window Definition Procedure, which is a <em>resource</em> — and it can come from the application's own resource fork and run as 68k code. An app with a custom WDEF draws arbitrary chrome that no native titlebar can reproduce.</td></tr>
<tr><td><b>The guest manages its own windows</b></td><td>Hit-testing walks Executor's window list in its own Z-order; dragging is implemented by XOR-ing a grey outline into the shared framebuffer and polling to mouse-up. The host window manager has zero involvement, and occlusion is computed by Executor. Hand stacking to the host and its order can disagree with the visible region QuickDraw clips against.</td></tr>
</tbody>
</table>
</div>
<p>The historical evidence agrees. ARDI wrote the NeXTSTEP front end with full AppKit available and complete control
of their own source, and used <b>one window</b>. 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.</p>
<div class="note note--warn">
<h3>And GNUstep could not do it today regardless</h3>
<p>Five of the window features per-window integration would need are missing or inert: <code>-setStyleMask:</code>
has no implementation in libs-gui at all, so a window's style cannot change after creation;
<code>-setOpaque:</code> is a stub with a <code>FIXME</code> and no backend call behind it; window creation always
uses the shared screen visual, so there is no per-pixel ARGB transparency; shaped windows exist only as private
API used internally by drag views; and <code>-addChildWindow:</code> records children but never makes them follow
the parent. Window <em>levels</em> do map to real EWMH hints, but the always-above hint is never set —
"floating" relies on the window manager inferring it, which KWin and Mutter generally do not.</p>
</div>
<div class="note note--ok">
<h3>Ship v1 without rootless at all</h3>
<p>Leave the rootless flag at its default and Executor draws a normal Mac desktop in a normal window — every
rootless path short-circuits cleanly. That drops the region mask and window transparency, which are the shakiest
parts of GNUstep's backends and exactly where you least want to be on day three. Turn it on behind a flag once the
basics hold.</p>
</div>
</div>
</section>
<!-- ============================ SUBSYSTEMS ============================ -->
<section class="panel">
<div class="panel__bar">
<span class="panel__btn" aria-hidden="true">□</span>
<span class="panel__title">6 — Subsystems</span>
<span class="panel__btn" aria-hidden="true">×</span>
</div>
<div class="panel__body">
<div class="tw">
<table>
<thead><tr><th style="width:14%">Subsystem</th><th style="width:14%">GNUstep</th><th style="width:8%">Days</th><th>Approach</th></tr></thead>
<tbody>
<tr>
<td><b>Keyboard</b></td><td><span class="chip chip--ok">Good on X11</span></td><td class="n">4</td>
<td>GNUstep's X11 backend puts the <b>raw X11 hardware keycode</b> in <code>-[NSEvent keyCode]</code>, so <code>x_keycode_to_mac_virt[]</code> is reused verbatim. Ignore <code>-characters</code> entirely — the core runs the guest's own KCHR and would double-translate.</td>
</tr>
<tr>
<td><b>Mouse</b></td><td><span class="chip chip--ok">Good</span></td><td class="n">1.5</td>
<td>Six overrides. Set <code>acceptsMouseMovedEvents</code>, override <code>-isFlipped</code> to <code>YES</code> to delete all the Y-flip arithmetic, and fold the right button into the left.</td>
</tr>
<tr>
<td><b>Clipboard</b></td><td><span class="chip chip--warn">Partial</span></td><td class="n">4</td>
<td><code>NSPasteboard</code> maps onto the 1995 code almost line for line. Interop is the risk: it needs the external <code>gpbs</code> daemon and cross-application exchange is documented as effectively plain-text-only. Keep a raw X11 fallback.</td>
</tr>
<tr>
<td><b>Sound</b></td><td><span class="chip chip--stop">Not via AppKit</span></td><td class="n">6</td>
<td>See below. Fully deferrable.</td>
</tr>
<tr>
<td><b>Printing</b></td><td><span class="chip chip--ok">Do nothing</span></td><td class="n">0.5</td>
<td>Already works and is entirely independent of the front end — the core generates PostScript and pipes it to <code>lpr</code>. Do not port <code>NEXTprint.m</code>. Do not touch <code>MacPrintClass.h</code>, which has no implementation file anywhere and zero references.</td>
</tr>
</tbody>
</table>
</div>
<div class="note note--ok">
<h3>Correction: GNUstep does still have the PostScript operators</h3>
<p>The obvious assumption — Display PostScript is dead, so all of it must be rewritten — is wrong.
GNUstep ships live <code>PS*</code> and <code>DPS*</code> operators as a real C function-pointer dispatch table on
the graphics context, the same path AppKit uses internally. Colour, gstate, matrix, path, text and even the NeXT
compositing extensions are all present, and <code>DPSPrintf</code> is a genuine variadic implementation.</p>
<p>The total Display PostScript surface in the old front end is about ten call sites, and most compile unchanged
— only two need substituting, plus two header renames. The <code>NSView</code> printing callback protocol is
fully implemented too, none of it stubbed. And the <code>pswrap</code> input file that looked like a problem
contains exactly one line: <code>% no longer needed</code>.</p>
<p>The recommendation is still to leave printing alone, because the Linux path already works without any of this.
But the cost of touching it later is much lower than it appears.</p>
</div>
<h2>Sound</h2>
<p>GNUstep's <code>NSSound</code> plays complete, pre-existing files through loadable sink bundles. There is no
PCM callback and no streaming-buffer API — nothing resembling <code>SDL_AudioCallback</code>. Executor
synthesises audio on the fly from the guest's <code>snd </code> resources at guest-chosen sample rates with hard
latency requirements, and that cannot be expressed through the current interface.</p>
<p>It matters less than it sounds. Executor's sound goes through its own <code>SoundDriver</code> 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: <b>modern Executor is silent on every current front
end anyway</b>, 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.</p>
<div class="two">
<div class="card">
<h3>SDL2 audio</h3>
<p>The pragmatic default. A working 171-line SDL1 implementation already exists in the tree; moving it to
<code>SDL_OpenAudioDevice</code> is largely mechanical. No new dependency the project doesn't already have.</p>
</div>
<div class="card card--keep">
<h3>SoundKit <span class="chip chip--ok">available today</span></h3>
<p>NEXTSPACE's <code>Frameworks/SoundKit</code> is a PulseAudio-backed GNUstep framework with a NeXT-style API.
<code>SNDPlayStream</code> exposes <code>-playBuffer:size:tag:</code> with write and empty callbacks —
precisely the hunger model, already built. <b>GPL v2+</b>, so it makes the resulting binary GPL.</p>
</div>
<div class="card">
<h3>Streaming <code>NSSound</code></h3>
<p>The preferred endpoint if the in-progress work lands. Would need a new <code>GSSoundSink</code> exposing an
application-supplied buffer source. Nothing to this effect appears in libs-gui's public branches yet.</p>
</div>
</div>
<p>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.</p>
</div>
</section>
<!-- ============================ TRAPS ============================ -->
<section class="panel">
<div class="panel__bar">
<span class="panel__btn" aria-hidden="true">□</span>
<span class="panel__title">7 — Traps</span>
<span class="panel__btn" aria-hidden="true">×</span>
</div>
<div class="panel__body">
<p class="lede">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.</p>
<ol class="traps">
<li><b>The update deadlock.</b> <code>requestUpdate()</code> is always called with the driver mutex held, and your
draw path takes the same mutex. Marshal with <code>waitUntilDone:NO</code>. Blocking there hangs on the first
frame, every time. Conversely <code>setMode</code> and the cursor methods are called <em>without</em> the mutex and
may block.</li>
<li><b>The bitmap format flag.</b> The exact equivalent of what <code>updateBuffer()</code> emits is
<code>NSAlphaFirstBitmapFormat | NSBitmapFormatThirtyTwoBitLittleEndian</code>. 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.</li>
<li><b>A wrong pixel format silently costs you 307,200 iterations per frame.</b> 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. <b>Use 8 bits per channel, 32 bits per pixel, device RGB.</b> Executor's colour spec is
fully parameterised, so this is a constants change.</li>
<li><b>The 2-bit grayscale path draws nothing at all.</b> 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.</li>
<li><b>Call <code>[view allocateGState]</code>.</b> The old code does this with the comment "since we will be
repeatedly focused on." Without it, per-frame <code>lockFocus</code> is ruinous and you will misdiagnose it as the
conversion being slow.</li>
<li><b>Target the X11/cairo backend, not Wayland.</b> GNUstep's Wayland backend emits no
<code>NSFlagsChanged</code> events at all, so command, shift and option are simply dead, and it zeroes the keycode
for Enter and Delete.</li>
<li><b>Modifiers are keys, not flags.</b> 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 <code>keyboardEvent</code> calls for the modifier keys
themselves.</li>
<li><b>Grab the keyboard aggressively.</b> Return <code>YES</code> unconditionally from
<code>-performKeyEquivalent:</code> while a guest application is running, or the host menu swallows ⌘Q,
⌘W and friends before the guest sees them.</li>
<li><b>Call <code>disableCursorRects</code> once, wholesale.</b> AppKit's cursor rectangles will otherwise fight
the emulator for the pointer continuously.</li>
<li><b>The XOR cursor.</b> 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.</li>
<li><b>Fix <code>resumeEvent</code> while you're here.</b> Qt hardcodes <code>true</code>, SDL2 hardcodes
<code>false</code>, 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.</li>
<li><b>Don't inherit the singleton-via-file-statics pattern.</b> The old code apologises for it in its own source.
Hold your view and window as members of the driver object.</li>
</ol>
</div>
</section>
<!-- ============================ SALVAGE ============================ -->
<section class="panel">
<div class="panel__bar">
<span class="panel__btn" aria-hidden="true">□</span>
<span class="panel__title">8 — What to read, what to delete</span>
<span class="panel__btn" aria-hidden="true">×</span>
</div>
<div class="panel__body">
<div class="two">
<div class="card card--keep">
<h3>Worth reading closely</h3>
<ul>
<li><b>The core bridge</b> — about 250 lines spanning init, screen update and <code>drawRect:</code>.
Port the shape, retype every line.</li>
<li><b>The <code>-step</code> pump</b> — run guest code until the host has an event pending, then yield.
Good heuristic; its asm-coroutine implementation is not.</li>
<li><b>The clipboard</b> — five flavours with generation counters, CR/LF conversion, and a synthesised
RTF font table built from the guest's own FOND resources. Genuinely hard-won, and better than anything the
modern tree has.</li>
<li><b>Focus to suspend/resume</b> — including the change-count gate.</li>
<li><b>The flush-policy comment</b> — documents a real failure mode where skipping the flush lets
messages queue until the machine pages itself to death.</li>
</ul>
</div>
<div class="card card--drop">
<h3>Archaeology — do not port</h3>
<ul>
<li><b><code>OldMacViewClass.m</code></b>, all 2,907 lines. Superseded, not in the build, and its one unique
idea is dead code behind <code>if (0 && …)</code>.</li>
<li><b><code>blockinterrupts.m</code></b> — the author <code>#error</code>'d it himself: "succumbed to
bitrot." Contains a disabled attempt to run Mac callbacks by suspending a thread and rewriting its program
counter.</li>
<li><b>The context switcher</b> — m68k and i386 inline-asm coroutines over hand-built stacks. Modern
Executor uses a real thread.</li>
<li><b>The kernel module loader</b> — loads a setuid-root Mach server and probes for it by
<em>deliberately triggering SIGILL</em>.</li>
<li><b>Printing</b> — raw PostScript into a DPS context, with a 10,000-iteration timeout that exists for
one Excel bug and a deliberately false <code>%%BeginDocument:</code> comment to work around Word 5.</li>
<li><b>~80% of the app class</b> — registration keys, serial numbers, licence enforcement.</li>
</ul>
</div>
</div>
<div class="note note--stop">
<h3>And the one that looked like treasure: <code>HFS_XFer</code></h3>
<p>A 9,194-line utility for moving files on and off HFS volumes, which sounds exactly like what the desktop project
needs. Ignore it. It is a Mac Toolbox application, not a NeXTSTEP one — its only Objective-C is a 14-line
stub. Its 5,470-line HFS engine is wrapped first line to last in <code>#if defined(OUTDATEDCODE)</code>, and it is
a superseded fork besides: the maintained copies in mainline are 30–130% larger and, critically,
endian-corrected. The HFS_XFer copies contain <b>zero</b> byte-swap macros against 168 in the mainline B-tree
alone. It only ever ran on big-endian 68k, backed by a 2.88 MB static RAM array. It only ever worked on
floppies. Three live defects were found in passing, including an inverted bounds check guarding a
<code>memcpy</code>.</p>
<p>Two things in it are worth ten minutes each: the copy engine is a compact, correct specification of what "copy a
Mac file faithfully" means — create, data fork, resource fork, then restore Finder info and dates <em>last</em>
— and the auto-mount hook sketches a design worth stealing at about forty lines.</p>
</div>
</div>
</section>
<!-- ============================ PLAN ============================ -->
<section class="panel">
<div class="panel__bar">
<span class="panel__btn" aria-hidden="true">□</span>
<span class="panel__title">9 — Sequence</span>
<span class="panel__btn" aria-hidden="true">×</span>
</div>
<div class="panel__body">
<div class="tw">
<table>
<thead><tr><th style="width:6%">#</th><th style="width:26%">Step</th><th style="width:9%">Days</th><th>Done when</th></tr></thead>
<tbody>
<tr><td class="n">0</td><td><b>Spike the blit</b></td><td class="n">2</td><td>An <code>NSView</code> blitting a 640×480 32-bit <code>NSBitmapImageRep</code> at 60 fps against back-cairo on X11, with the format verified correct. <b>This is the only genuinely unknown question in the plan and nobody has answered it before. If it fails and the raw-Xlib escape hatch doesn't pan out, stop here</b> — everything after it would be wasted.</td></tr>
<tr><td class="n">1</td><td>Build skeleton</td><td class="n">1</td><td><code>front-end-gnustep</code> compiles and links, <code>executor-gnustep</code> runs headless-equivalent and exits cleanly.</td></tr>
<tr><td class="n">2</td><td>Window and framebuffer</td><td class="n">2</td><td>Event loop, <code>setMode</code>, <code>requestUpdate</code> and the draw path work against a solid grey framebuffer. No input yet. Non-rootless.</td></tr>
<tr><td class="n">3</td><td>Mouse</td><td class="n">1.5</td><td>The guest tracks the pointer and clicks land. Cursor shape and visibility follow.</td></tr>
<tr><td class="n">4</td><td>Keyboard</td><td class="n">4</td><td>Typing works in a real application, modifiers included, and ⌘-equivalents reach the guest rather than the host menu.</td></tr>
<tr><td class="n">5</td><td>Clipboard, TEXT only</td><td class="n">1</td><td>Copy and paste between a classic application and a GNUstep one. Parity with the current X11 front end.</td></tr>
<tr><td class="n">5b</td><td>App shell</td><td class="n">2</td><td>Menu bar, about panel and window construction, all in code. Qt ships none of this; a native-feeling GNUstep app needs it.</td></tr>
<tr><td class="n">—</td><td><b>Milestone one</b></td><td class="n"><b>~8</b></td><td><b>A usable native front end.</b> Sound faked, printing via the existing path, single window.</td></tr>
<tr><td class="n">6</td><td>Rootless</td><td class="n">3</td><td>Mac windows float over the Gershwin desktop with no surrounding grey.</td></tr>
<tr><td class="n">7</td><td>Clipboard flavours</td><td class="n">3</td><td>PICT, TIFF and RTF, with the font-table synthesis. Exceeds every current front end.</td></tr>
<tr><td class="n">8</td><td>Sound</td><td class="n">6</td><td>A <code>SoundDriver</code> subclass against whichever backend won.</td></tr>
</tbody>
</table>
</div>
<div class="note note--ok">
<h3>Start with step 0, not step 1</h3>
<p>Everything after it is ordinary work with a known shape. Step 0 is the only item that can invalidate the whole
design, and it costs two days to settle. If the cairo path can't sustain the blit, the mechanical escape hatch is
real — <code>-[NSWindow windowRef]</code> is implemented and on X11 hands back a structure exposing the
<code>Display *</code> and drawable, from which <code>XShmPutImage</code> is reachable. But no one has ever done
that either, and it may require an internal header that distributions don't ship. Find out on day one.</p>
</div>
<h2>Open: four libraries not yet reviewed</h2>
<p>This review read Executor's two trees plus <code>libs-gui</code> and <code>libs-back</code>. Four more libraries
were not read, and each could materially change a conclusion here — two of them the most expensive
conclusions. <b>Review these before committing to the architecture.</b></p>
<div class="tw">
<table>
<thead><tr><th style="width:20%">Library</th><th style="width:24%">What it is</th><th>Why it could change this plan</th></tr></thead>
<tbody>
<tr>
<td><code>libs-opal</code></td>
<td>Core Graphics for GNUstep</td>
<td><b>Highest potential impact.</b> The top risk in this plan is blit throughput through
<code>NSBitmapImageRep</code>, which round-trips X with no shared memory and no surface caching. If Opal
offers a usable <code>CGBitmapContext</code> or <code>CGImage</code> path to the screen, that could be a
better route than AppKit's — and it would matter most in exactly the place the plan currently calls
unproven. Caveats already known: its indexed colour space file was last touched in 2010, and Opal's backend
was non-functional for years until a libs-back change landed in April 2026.</td>
</tr>
<tr>
<td><code>libs-quartzcore</code></td>
<td>CoreAnimation for GNUstep</td>
<td>Bears on rootless. This plan concludes that per-Mac-window host windows are impossible and that the
shaped-mask approach is the ceiling. <b>Layers are a third option neither the Qt nor Wayland front ends
consider.</b> If a working layer implementation exists, per-window compositing might be reachable without
the core rewrite section 5 describes — still bounded by the same guest-writes-to-screen-memory
problem, but worth knowing before the question is closed.</td>
</tr>
<tr>
<td><code>NSSound</code> <span class="cite">in libs-gui</span></td>
<td>Sound playback</td>
<td>The verdict here — that it cannot serve Executor's hunger model because it has no PCM callback
— was reached by reading the current implementation. <b>Work is reportedly in progress.</b> If a
streaming sink lands, the AppKit-native path becomes viable and the SDL2 and SoundKit options become
fallbacks rather than the plan. Worth confirming directly with whoever is doing it whether it is a new
<code>GSSoundSink</code>, a fork, or staged outside the public branches.</td>
</tr>
<tr>
<td><code>libs-corebase</code></td>
<td>CoreFoundation for GNUstep</td>
<td>Lowest impact but cheapest to check. Relevant to how much of the front end must be Objective-C at all
— a C-level interop layer could let more of the bridge stay in plain C++17 rather than
Objective-C++, which shrinks the surface exposed to the runtime and exception-interop traps in
section 4.</td>
</tr>
</tbody>
</table>
</div>
<p>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.</p>
<h2>What nobody could determine</h2>
<p>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:</p>
<ul>
<li>The literal output of <code>gnustep-config --objc-flags</code> on a current install. The flags above are
derived from gnustep-make's own makefiles, not observed.</li>
<li>Whether distribution <code>-dev</code> packages install the internal header that gates the raw-Xlib escape
hatch.</li>
<li>Any GNUstep drawing benchmark newer than 2015.</li>
<li>Whether recent binutils fixed the GNU ld problem, or whether lld remains mandatory.</li>
<li>First-hand reports for window levels under KWin, Mutter or i3 — the always-above gap is inferred from
source only.</li>
</ul>
</div>
</section>
<!-- ============================ PROVENANCE ============================ -->
<section class="panel">
<div class="panel__bar">
<span class="panel__btn" aria-hidden="true">□</span>
<span class="panel__title">10 — Provenance and licensing</span>
<span class="panel__btn" aria-hidden="true">×</span>
</div>
<div class="panel__body">
<div class="tw">
<table>
<thead><tr><th style="width:26%">Component</th><th style="width:18%">Licence</th><th>Consequence</th></tr></thead>
<tbody>
<tr><td>Executor core</td><td><b>MIT</b></td><td>Cliff Matthews open-sourced it in 2008. No ROM, no Apple system software, no redistribution problem.</td></tr>
<tr><td>cxmon (debugger)</td><td>GPL v2+</td><td>Optional and removable. A stock build is effectively GPL-bound; for a GPL distribution this is moot.</td></tr>
<tr><td>New GNUstep front end</td><td>your choice</td><td>MIT keeps it contributable upstream as a clean component.</td></tr>
<tr><td>SoundKit, if used</td><td>GPL v2+</td><td>Makes the binary GPL. Fine for the distro; blocks an MIT-clean upstream contribution if the front end hard-depends on it.</td></tr>
<tr><td>GNUstep</td><td>LGPL / GPL</td><td>Library linkage as normal.</td></tr>
</tbody>
</table>
</div>
<p>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.</p>
</div>
</section>
</div>
<footer>
Prepared 27 July 2026 from a five-agent review of both source trees ·
fork at <a href="https://github.com/pkgdemon/executor">pkgdemon/executor</a> ·
modern tree <a href="https://github.com/autc04/executor">autc04/executor</a> ·
<a href="https://github.com/trunkmaster/NEXTSPACE/tree/master/Frameworks/SoundKit">NEXTSPACE SoundKit</a>
</footer>
</body>
</html>