Skip to content

build-macos CI job + macOS documentation - #763

Open
Depal1 wants to merge 3 commits into
OoliteProject:masterfrom
Depal1:pr-3-ci-docs
Open

build-macos CI job + macOS documentation#763
Depal1 wants to merge 3 commits into
OoliteProject:masterfrom
Depal1:pr-3-ci-docs

Conversation

@Depal1

@Depal1 Depal1 commented Oct 9, 2026 •
edited
Loading

Copy link
Copy Markdown

DRAFT: PR #3, build-macos CI job + macOS documentation

Base: master @ 8ffe02d. Branch: pr-3-ci-docs.
Commits in this PR: 6d35c2f (build-macos job + release-job artifact exclusion), e319446 (README status fix + Documentation/BUILDING-macOS.md).
Depends on: PR #1 (the darwin build) and PR #2 (the js artifact).

What this adds

A build-macos CI job (.github/workflows/build-all.yaml), shaped like the
existing build jobs:

  • runs-on: macos-26 (arm64; the image ships Xcode 26.x, whose SDK matches the
    documented minimum).
  • Homebrew dependencies: meson, ninja, pkg-config, libpng, openal-soft, libvorbis, nspr,
    zlib, sdl3, espeak-ng.
  • One trap worth documenting in review: meson's pkg_config_path is a sticky build
    option. If the first configure runs without it, pkg-config misses the keg-only
    formulas and meson silently falls back to Apple's deprecated OpenAL framework; plain
    reconfigure does not re-resolve. The job passes -Dpkg_config_path on the first setup
    and exports it as well.
  • The SpiderMonkey artifact is fetched, not built (the macos-26 image has no python2,
    which the js185 configure requires; the artifact repo carries its own build CI). Until
    the mozillajs-macos release is published, the job stages a vendored, verified
    tarball; the swap to a download is a one-line change commented in the workflow.
  • Produces an unsigned oolite-macos-arm64 artifact (dev flavor). Notarization needs a
    Developer ID identity; that question is tracked in the design issue and does not block
    the code.

The release job is protected. The mac artifact is excluded from the release
download (with a pattern: allow-list and a comment), because the release job
hard-asserts an exact artifact-file count and an unsigned .app has no place in a public
release yet. The assert itself is untouched; build-macos joins needs: so the
ordering stays deterministic.

Documentation. README's "OSX is not supported" statements become the real status:
native Apple Silicon builds exist in this series, minimum macOS 26, with Intel/x86_64
noted as a documented near-term follow-up (nothing in the port is arm64-inherent; the
SpiderMonkey artifact already builds for x86_64). New Documentation/BUILDING-macOS.md
covers prerequisites, the pkg_config_path trap, bundle layout and launch, the debug
flavor and the TCP debug console, the SpiderMonkey artifact provenance, the two
documented engine deviations (interpreter-only; pcre regexes), the SDR output parity
statement (true HDR output is Windows-only upstream), and the signing prerequisites for
distribution. Markdownlint-clean per the existing config.

Relation to open issues

  • Apple silicon release #721 restriction check: the CI job builds the dependency stack the same way the Linux
    and Windows jobs do (package manager + Meson), uses espeak-ng as the speech dependency
    (it is a hard meson dependency on every platform), and adds no OS-specific code beyond
    the workflow itself. The docs state the SDL3/meson/espeak-ng compliance that PR Memory spike on wormhole chaining #1
    implements.
  • ARM Mac build is broken. #360: the README's unsupported-OSX language is the user-facing form of the same issue;
    this PR is the first thing that makes the statement outdated, so it leads the diff.

Verification

  • YAML parses; actionlint reports no new findings versus HEAD.
  • A full simulation of the job ran on the same host class (macos-26/arm64/Homebrew):
    fresh clean setup with the exact CI command took the -Dpkg_config_path option,
    resolved OpenAL Soft 1.25.2 (not Apple's framework), resolved all dependencies, built,
    staged the bundle, and passed the ad-hoc codesign gate. Exit 0.
  • Not yet verified on a real runner: pushing to a fork requires account access; that is
    the one remaining step, listed in the PR description when filed.

AI-assistance disclosure: developed with AI assistance (GLM-5.3-Flash); verified by the builds/tests described.

Design issue: #760

Depal1 added 3 commits October 8, 2026 23:36
@Depal1
Darwin: install script for the SpiderMonkey js185 arm64 artifact
5447da6 
Downloads the mozillajs-macos release artifact (interpreter-only js185 for
aarch64, built from this org's spidermonkey-ff4 source with the pcre regex
path, mirroring the mozillajs-linux flow) and stages include/ + lib into
build/mozilla_js for the Meson darwin scan. Prerequisite for the Apple
Silicon build described in oolite#721; one of the blockers listed in
oolite#360.
@Depal1
Darwin host support: native Apple Silicon build (SDL3/Meson, feature …
716c061 
…parity with Linux)

Adds darwin as a build host for the existing Meson + SDL3 stack and the
source changes needed to run on Apple Silicon at parity with the Linux
build. Prepared against oolite#721 and oolite#360; see the design issue for
the full validation evidence.

Build system:
- clang-darwin.ini native file (no lld on macOS; the thinlto cache flag is
  lld-only, darwin uses ld64's -cache_path_lto spelling)
- mk.sh selects the native file by host; get_version.sh made
  bash-3.2/BSD-date portable (Linux output byte-identical)
- src/meson/darwin: framework linkage, -DOOLITE_SDL=1, Apple-Foundation
  defines, js artifact scan (js_static), @executable_path/../Frameworks
  rpath; GNUstep runtime defines stay Linux-only
- Meson LTO cache flag host-guarded (lld-only spelling broke darwin linking)

Source re-gate:
- OOLITE_MAC_APPKIT (OOLITE_MAC_OS_X && !OOLITE_SDL) defined once in
  OOFoundation.h; 28 Cocoa-backend gate sites moved onto it (GameController,
  speech, fullscreen controller, OXP verifier). OOLITE_MAC_OS_X now carries
  only Apple-Foundation idioms. main() becomes a real SDL3 entry point.
  The binary links no AppKit (otool-verified).

Renderer legacy-GL layer (darwin only; Linux/Windows still require GL 3.3
and compile the original GLSL-330 shaders byte-identically):
- capability gate replaces the 3.3 version check (2.1 + EXT_framebuffer_object)
- non-MSAA FBO path; DEPTH_COMPONENT24; runtime RGBA16F->RGBA8 and
  single-target-MRT fallbacks wired into the existing completeness checks
- VAOs removed from the postFX quad (explicit attribute arrays)
- GLSL-120 variants of the three postFX shaders behind OO_LEGACY_GL
  (non-darwin preprocessed shader input byte-identical to master)
- dFdx/dFdy specular filter gated; glClampColor guarded out
- CFBundleVersion in the bundle plist (ResourceManager version gate)

Audio/hardening/packaging:
- espeak-ng speech active on darwin (NSSpeechSynthesizer region gated off,
  per the OoliteProject#721 discussion); OpenAL Soft linked
- post_build split into per-platform functions; darwin fn assembles a real
  Contents/ bundle, bundles non-system dylibs with @rpath, ad-hoc re-signs
  every Mach-O after edits, dsymutil/strip; meson install skipped on darwin
- console-attached startup stall fixed (Apple NSInputStream -read: blocks
  when drained; GNUstep returns)
- v-sync via refresh-period swap pacing (SDL_GL_SetSwapInterval is not
  enforced over NSOpenGLContext on this OS); ~74 fps on a 75 Hz display
- portable NSString selector + removeItemAtPath:error: (upstream-quality)
- ResourceManager builtInPath fall-through fix on the Mac arm
  (upstream-quality)

Known limitations (documented in Documentation/BUILDING-macOS.md):
- Joystick support is compiled and initialized through SDL3 but has NOT been
  tested with physical hardware; the validation log reports zero sticks
  because none was attached. Treat joystick support as untested.
- True HDR output remains Windows-only upstream; macOS renders the same SDR
  ACES/bloom/postFX output as Linux.
- The SpiderMonkey js185 dependency is built interpreter-only with pcre
  regexes on arm64 (no JIT backend exists in js185 for this architecture);
  delivered by the companion SpiderMonkey PRs + mozillajs-macos artifact
  (PR OoliteProject#2). Native arm64 interpreter benchmarks faster than the x86_64
  Rosetta path in all harness kernels.

Validation: 82-minute scripted soak, 11 game processes, zero crashes;
preference persistence and save/load round-trips verified (including a
1.90-mac commander); 6 real OXPs installed and booted with zero JS errors.
Full evidence pack in the series design issue.
@Depal1
CI build-macos job + macOS documentation; README status fix
a108648 
build-macos: macos-26 runner, Homebrew deps, the SpiderMonkey arm64
artifact staged via ShellScripts/Darwin/install_mozilla_js.sh (interpreter-
only js185 + pcre regexes; the two documented darwin deviations), dev build
with -Dpkg_config_path set on the FIRST setup (the option is sticky; a
first setup without it silently resolves Apple's deprecated OpenAL
framework instead of OpenAL Soft), unsigned artifact upload.

The release job's exact artifact-count assert is untouched: build-macos is
added to needs: for deterministic ordering and the mac artifact is excluded
from the release download pattern (it is unsigned; notarization needs a
Developer ID identity, tracked in the series design issue).

Docs: README macOS status updated (native Apple Silicon build, minimum
macOS 26, Intel/x86_64 noted as a documented near-term follow-up);
Documentation/BUILDING-macOS.md added (prerequisites including the
pkg_config_path trap, bundle layout and launch, debug flavor + TCP console,
artifact provenance, the two js deviations, the SDR output parity
statement, signing prerequisites, known limitations).

Note: joystick support is compiled and initialized through SDL3 but has
NOT been tested with physical hardware (no joystick was attached during
validation; the log reports zero sticks). Treat it as untested.

Closes part of oolite#721 (Apple silicon release prerequisites) with PR OoliteProject#1
and PR OoliteProject#2; background in oolite#360.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@oocube oocube Awaiting requested review from oocube oocube is a code owner
@mcarans mcarans Awaiting requested review from mcarans mcarans is a code owner
@phkb phkb Awaiting requested review from phkb phkb is a code owner
@mwerle mwerle Awaiting requested review from mwerle mwerle is a code owner
@Kaks Kaks Awaiting requested review from Kaks Kaks is a code owner
@AnotherCommander AnotherCommander Awaiting requested review from AnotherCommander AnotherCommander is a code owner
@ericwalch ericwalch Awaiting requested review from ericwalch ericwalch is a code owner
@dsalt dsalt Awaiting requested review from dsalt dsalt is a code owner
@KonstantinosSykas KonstantinosSykas Awaiting requested review from KonstantinosSykas KonstantinosSykas is a code owner
@kanthoney kanthoney Awaiting requested review from kanthoney kanthoney is a code owner
@jobi-wan jobi-wan Awaiting requested review from jobi-wan jobi-wan is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Depal1