MAD_MACOS.md – Multiplatform Frameworks and the Native macOS ApplicationThis page records the multiplatform framework audit and the native macOS application architecture. The user-facing guide is at /macos.html.
Written on the original date; current-state facts reconciled 2026-11-22.
This document records the architecture decision, the framework-by-framework portability
audit, and the phased migration and implementation plan for making the MAD frameworks
genuinely multiplatform (iphoneos, iphonesimulator, macosx, and headless Linux)
and building the native macOS (AppKit) frontend for MAD Designer.
AppKit) vs. Mac CatalystDecision: Build a native macOS application (macosx SDK, AppKit) over shared
multiplatform frameworks (MACOSX_DEPLOYMENT_TARGET = 12.0, supporting every Apple
Silicon Mac and Intel Macs on Monterey or newer). Mac Catalyst is rejected.
| Dimension | Native macOS (macosx / AppKit) |
Mac Catalyst (maccatalyst / UIKit) |
|---|---|---|
Static C libraries (Compressor) |
Already built. All 10 .xcframework bundles in Compressor/library/ carry universal macosx (arm64 + x86_64, -mmacosx-version-min=11.0) slices verified by ./Compressor/build.sh --verify --all --platforms ios,simulator,macosx. |
Missing. Zero maccatalyst slices (-target <arch>-apple-ios15.0-macabi) exist. The Mach-O linker rejects linking MACOS archives into MACCATALYST binaries; Catalyst would require adding a 4th platform to Compressor and rebuilding all 10 C libraries (openssl, mariadb, postgres, freetds, libarchive, sqlite3, zint, libpng, bzip2, zlib). |
| Core engine portability | 90% complete. The Linux headless port (MAD_LINUX.md) already removed Core Data from MAD.framework, decoupled database drivers (MADDatabaseDriverRegistry) and report exporters (MADReportExporterRegistry), and introduced MADHeadlessDocument, MADSQLQueryCompiler, and MADDesignerLayout. |
Same engine, but tied to UIDocument and iOS background task lifecycles. |
| Desktop ergonomics | Native NSDocument / NSDocumentController (Finder double-click, Cmd+N, Cmd+O, Cmd+S, Cmd+Shift+S, Recent Documents, window restoration, NSUndoManager), native split views, native table/outline views, native PDFView / WKWebView, and standard macOS menus. |
Nested zooming UIScrollView + UICollectionView sections, iOS tab/navigation bars, UIPickerView wheels, and iOS sandboxed document browser (MADExplorer). Apple Silicon Macs already run the iPad build via Designed for iPad. |
| Distribution via GitHub | Clean standalone .app bundle packaged as a downloadable .dmg and .zip on GitHub Releases (arm64 + x86_64). |
Requires Catalyst provisioning profile and entitlements mismatching outside-the-App-Store distribution ergonomics. |
Compressor)All ten vendored C libraries in Compressor build universal macosx (arm64 + x86_64)
slices with -mmacosx-version-min=11.0:
| Library | Version | ios (arm64) |
simulator (arm64 + x86_64) |
macosx (arm64 + x86_64) |
Used By |
|---|---|---|---|---|---|
sqlite3 |
3.53.3 | Yes | Yes | Yes | MADSqlite3, MAD |
zlib |
1.3.2 | Yes | Yes | Yes | MAD, MADMySQL, MADPostgres, MADBarcodes |
openssl |
3.5.9 | Yes | Yes | Yes | MADTds, MADMySQL, MADPostgres |
bzip2 |
1.0.8 | Yes | Yes | Yes | MAD |
libpng |
1.6.59 | Yes | Yes | Yes | MADBarcodes |
libarchive |
3.8.9 | Yes | Yes | Yes | MAD |
freetds |
1.4.27 | Yes | Yes | Yes | MADTds, MADTdsClient |
mariadb |
3.4.11 | Yes | Yes | Yes | MADMySQL |
postgres |
17.11 | Yes | Yes | Yes | MADPostgres |
zint |
2.16.0 | Yes | Yes | Yes | MADBarcodes |
Verification command:
./Compressor/build.sh --verify --all --platforms ios,simulator,macosx
Twelve frameworks form the multiplatform stack (iphoneos, iphonesimulator, macosx,
plus Linux for the twelve headless frameworks):
MADFoundation (28 .m files):
MADApplication.h: guard <UIKit/UIApplication.h> with #if TARGET_OS_IPHONE
instead of #if __APPLE__ (MADApplication.m already has
#elif TARGET_OS_OSX #import <AppKit/NSApplication.h>).MADURLFactory.m: guard <UIKit/UIScreen.h> with #if TARGET_OS_IPHONE and use
NSScreen.mainScreen.backingScaleFactor > 1.0 on TARGET_OS_OSX.MADKeyChain.m: uses Security.framework, which is native on both iOS and macOS.MADDataStructures (17 .m files):
MADFileManager (11 .m files):
#import <MobileCoreServices/UTType.h> in
MADMetaDataLocal.m:16 (<UniformTypeIdentifiers/UTType.h> is already imported on
line 17).MADCocoaExtensions (17 .m files):
CGGeometry+Extras.h: provide UIEdgeInsets (NSEdgeInsets-compatible layout
struct + UIEdgeInsetsMake / UIEdgeInsetsZero / UIEdgeInsetsEqualToEdgeInsets),
NSStringFromCGPoint / NSStringFromCGSize / NSStringFromCGRect, and
NSValue (MADCGGeometryExtensions) (valueWithCGPoint:, CGPointValue,
valueWithCGRect:, CGRectValue, valueWithCGSize:, CGSizeValue) on
TARGET_OS_OSX.MADColor.h / MADColor.m: bridge MADColor to NSColor on TARGET_OS_OSX while
keeping UIColor on TARGET_OS_IPHONE.UIView, UIAlertController, UITextField, and UIColor
categories with #if TARGET_OS_IPHONE.MADAPI (11 .m files):
MADConnectionViewController and MADConnectionSQLGenericViewController
with #if TARGET_OS_IPHONE.MADSqlite3 (26 .m files):
sqlite3.xcframework. Zero source changes required.MADTds (1 .m file):
freetds.xcframework + openssl.xcframework. Zero source
changes required.MADTdsClient (4 .m files):
MADDatabaseSQLServer, MADTdsConnection, and MADDataTypeSQLServer are pure
Foundation. Guard MADTdsConnectionViewController with #if TARGET_OS_IPHONE.MADMySQL (19 .m files):
mariadb.xcframework. Guard
MADMySQLConnectionViewController with #if TARGET_OS_IPHONE.MADPostgres (5 .m files):
postgres.xcframework. Guard
MADPostgresConnectionViewController with #if TARGET_OS_IPHONE.MADBarcodes (70 .m files):
zint.xcframework.MADBarcode, MADBarcodeCache, and MADBarcodeView: bridge UIImage / NSImage
and UIView / NSView on TARGET_OS_OSX over the existing CGImageRef
MADBarcodeImageFromZintBitmap pipeline.MAD (199 .m files):
#if __APPLE__ with #if TARGET_OS_IPHONE and #elif TARGET_OS_OSX
AppKit bridges across the 9 shared model/rendering files (RptqObject.m,
RptqDocumentElementImage+Extras.m, RptqDocument+Extras.m,
RptqDocumentSection+Extras.m, RptqDocumentElement+Extras.m,
MADPrintPageElement.m, MADElementStylizedText.m, MADFonts.m, and
MADReportExporterPDF.m).MADReportExporterPDF.m, render paginated PDFs on TARGET_OS_OSX using
CGPDFContextCreateWithURL / CGPDFConsumerCreateWithCFData and
NSGraphicsContext (+graphicsContextWithCGContext:flipped:YES), so
MADPrintPageRenderer and MADPrintPageElement draw natively on macOS.UIDocument (MADocument), UIView, and
UICollectionViewLayout files with #if TARGET_OS_IPHONE.MADExplorer remains iOS-only (macOS uses NSDocumentController, Finder, and NSOpenPanel with a primary New Document button). MADFeedback and Scrimpter remain unused per
AGENTS.md.
docs/project/registers/BUGS.md to docs/project/registers/BUGS_FIXED.md with unit tests:
MADKeyChain (MADFoundation/Source/MADKeyChain.m): stopped requesting
kSecReturnData : @YES (and leaking the returned CFDataRef) in
+credentialsExist:, +saveToken:forKey:withDescription:, +deleteKey:, and
+deleteSavedPasswordForKey:error:.MADURLFactory (MADFoundation/Source/MADURLFactory.m): guarded
+newURLForLocalApplicationSupportDirectory when [NSBundle mainBundle].bundleIdentifier
is nil (falling back to [MADApplication groupIdentifier]), and guarded
containerURLForSecurityApplicationGroupIdentifier: with
#if defined(__APPLE__) && TARGET_OS_IPHONE so unentitled macOS processes use
standard per-user directories instead of triggering TCC prompts on
~/Library/Group Containers/.MADDataTable (MADFoundation/Source/MADDataTable.m): guarded
NSDataWritingFileProtectionCompleteUnlessOpen with
#if defined(__APPLE__) && TARGET_OS_IPHONE so unentitled macOS cache writes succeed.MADDatabaseSqlite3 (MADSqlite3/Source/MADDatabaseSqlite3.m): guarded
[dataTable endBulkInsert] with if (rowCounter > 0) so zero-row SELECT queries
do not execute COMMIT TRANSACTION when [dataTable beginBulkInsert] was never
called.MADBarcode (MADBarcodes/MADBarcodes/MADBarcodes/MADBarcode.m): fixed
-drawInRect: doubling rect.origin when self.center == YES.MADDesignerLayout (MAD/Source/MADDesignerLayout.m): preserved each selected
element’s own prior value in a dictionary when registering undo actions across all
bulk-update methods (setFontsize:, setFontname:, setVerticalAlignment:,
setHorizontalAlignment:, setSizeWidth:, setSizeHeight:, setMargin*,
setPadding*, setBorder*).macosx across the 12 framework Xcode projects:
SUPPORTED_PLATFORMS = "iphoneos iphonesimulator macosx" and
MACOSX_DEPLOYMENT_TARGET = 12.0.platformFilters = (ios, maccatalyst, ); on UIKit.framework references and
linked AppKit.framework with platformFilters = (macos, ); where needed.Ensure Libraries build phases to pass
--platforms ios,simulator,macosx.-destination 'platform=macOS,arch=arm64'):
MADFoundation: 199 tests passed, 0 failuresMADDataStructures: 72 tests passed, 0 failuresMADCocoaExtensions: 80 tests passed, 0 failuresMADFileManager: 85 tests passed, 0 failuresMADAPI: 106 tests passed, 0 failuresMADSqlite3: 118 tests passed (5 benchmarks skipped), 0 failuresMADTds: Built cleanly for macosxMADTdsClient: 77 tests passed (including live SQL Server suite), 0 failuresMADMySQL: All offline & live MariaDB/MySQL tests passed, 0 failuresMADPostgres: 31 tests passed (including live PostgreSQL suite), 0 failuresMADBarcodes: 30 tests passed, 0 failuresMAD: 650 tests passed, 0 failuresNSDocument Layer (Completed)MADHeadlessDocument):
+createDocumentAtURL:withDatabaseConnection:credentials:error: on
MADHeadlessDocument (MAD/Source/MADHeadlessDocument.h, .m), which connects to
any registered driver (SQLite3, MySQL, SQL Server, PostgreSQL), imports all
database tables (-getTablesFromConnection:error:) and columns
(-fieldsForTable:connection:error:) into RptqDatabaseSchemaTable /
RptqDatabaseSchemaField, initializes the standard report sections (Report Header,
Page Header, Report Detail, Page Footer, Report Footer), and writes the
portable .mad container.MADMacDocument (NSDocument subclass in Mac/Source/MADMacDocument.m):
MADHeadlessDocument (with automatic legacy Core Data .mad conversion via
MADStoreConverter when needed), conforms to MADocumentDesignerProtocol so
MADDesignerLayout records undo/redo directly onto NSDocument.undoManager, and
supports readFromURL:ofType:error:,
writeToURL:ofType:forSaveOperation:originalContentsURL:error:, and asynchronous
refreshWithCredentials:maxRows:completion:.Mac/) (Completed)Built under Mac/ (Mac/Source/, Mac/Resources/, Mac/Tests/, Mac/build.sh) and integrated into MAD Designer.xcodeproj via the MAD Designer Mac target and shared scheme:
MADMacAppDelegate, MADMacAboutWindowController & MADMacDocumentController):
MADStoreLegacyConverter, builds the native macOS main menu (MAD Designer, File, Edit with Undo/Redo, View workspace switching Cmd+1/Cmd+2/Cmd+3, Report refresh Cmd+R, Window, Help), and presents the standard NSOpenPanel on launch when no document is open.MADMacAboutWindowController presents the native About MAD Designer window (MAD Designer → About MAD Designer and Help menu items) with the engine version/build (MADMeta.plist) and the macOS application version (CFBundleShortVersionString) shown as distinct values, copyright and reserved brand/artwork notice, Source Code on GitHub action, and three tabbed sections: Overview (what MAD is, the 4-step reporting workflow, and supported drivers/bands/exporters), License & Notice (MIT License, NOTICE, and the written LGPL-3.0 relink offer for FreeTDS and MariaDB Connector/C), and Acknowledgements (interactive sidebar of all 16 third-party open-source components paired with their attributions and the 12 full license texts bundled under Contents/Resources/Licenses/).MADMacDocumentController configures NSOpenPanel with all .mad UTType identifiers (com.everydayapps.productivity.mad and com.thomason.report.mad) so existing .mad files are never dimmed out, and places a primary New Document button directly in the bottom-left bar of the Open Panel.MADMacConnectionWindowController):
.sqlite3/.db file via NSOpenPanel), MySQL, Microsoft SQL Server, and PostgreSQL, with Test Connection, MADKeyChain password storage, and Create Document… (NSSavePanel).MADMacWindowController):
MADMacQueryViewController):
200px left-hand Database Tables list (user-resizable
via NSSplitViewDelegate without snapping back, and held at a fixed width when the
window is resized so the visual canvas resizes instead) paired with an interactive
right-hand visual canvas (MADMacQueryCanvasView). Double-clicking a schema table
adds it to the query (populating all RptqQueryField rows) and displays it as a
draggable, resizable floating AppKit table card (MADMacQueryTableCardView +
MADMacQueryFieldTableView) styled with topological root/child headers (MTGraph),
and dragging from a field in one table card to a field in another creates a default
Left Outer Join (MADLinkTypeLeftOuterJoin) drawn via Bezier connectors and
join-type badges (MADMacQueryLinksOverlayView, matching iPad’s MADConnectorView).
Clicking or right-clicking a visual join connector opens a join inspector popover or
context menu to change the link type, swap direction, or delete the link; header
popovers provide Filters (WHERE), Groupings (GROUP BY), and Arrange Tables.MADSQLParser +
MADSQLStatementResolver + MADSQLQueryCompiler).MADMacDesignerViewController + MADMacDesignerCanvasView + MADMacDesignerMinimapView):
38pt height): Provides clickable and draggable SF Symbol
element palette items (Label, Data Field, Aggregate, Barcode,
Image, Line), quick multi-element alignment controls (Left, Center,
Right, Top, Middle, Bottom), Size to Fit, Grid / Snap /
Rulers toggles, and a Zoom slider with one-click 100% reset.NSSplitViewDelegate): Left navigator sidebar
defaults to 220pt (180–340pt), right inspector defaults to 260pt
(220–380pt), and both sidebars hold their widths across window resizes while
preserving user divider adjustments.MADMacDesignerMinimapView): Draws
proportional report bands with color-coded stripes, live miniature element blocks,
and a blue viewport rectangle; clicking or dragging jumps to and selects the band.NSSearchField) of all RptqQueryField
columns; dragging a field onto any section band on the canvas (or double-clicking)
inserts a bound RptqDocumentElementLabelDataField.MADMacDesignerCanvasView): Flipped, zoomable
NSView canvas with horizontal/vertical rulers, paper margins, color-coded section
bands, section height drag handles, smart alignment guides, grid snapping, marquee
selection, Shift-click multi-selection, 8-point resize handles, inline double-click
label editing, smart non-overlapping element placement
(-nextAvailableOriginInSection:forElementSize:), and cross-section drag-and-drop
(-moveElement:toSection:atOrigin:) with live target band highlighting and full
NSUndoManager integration.1 · PAGE & SELECTED SECTION): Paper size, selected band badge,
band height (pt) with Fit Height button, Section Visible, and Page Break
After.2 · SELECTED ELEMENT INSPECTOR):
4 grouped inspector cards (Element & Band Assignment with cross-section move
popup, Duplicate, and Delete; Content & Data Binding with static text,
query field binding, aggregate function & scope, currency formatting, and barcode
options; Typography & Appearance with font family/size, bold/italic/underline/
strikethrough, horizontal/vertical alignment, and text/background colors; and
Position, Size & Box Model with X, Y, W, H synchronized across both
rect.origin and dropPoint, plus borders, padding, and margin).MADMacViewerViewController):
40pt height): Page Size popup (MTPaper standard paper types: US Letter, US Legal, US Tabloid, A3, A4, A5, B4, B5, JIS B4, JIS B5), Refresh (Cmd+R), Zoom controls (-, 100%, +), Page Navigation (Previous, Page N of M, Next), Print… (Cmd+P via NSPrintOperation), and Export… (Cmd+E).PDFView): Renders paginated PDF pages at the selected paper size from the local SQLite table cache (MADDataTableFast) with page shadows and a bottom status bar (statusBarView) displaying rendered page count, cached row count, and paper dimensions.NSSavePanel): Configures an accessory format popup supporting all 7 registered exporters (PDF, HTML, HTML Flow, CSV, JSON, JSON Report, Plain Text) and dynamically updates the save panel’s allowed file extension../Mac/build.sh --smoke-test --package
Produces:
Mac/build/MAD Designer.app (standalone native macOS app bundle with all 12
frameworks and legacy Core Data .momd models embedded and signed)Mac/build/MAD-Designer-macOS.zipMac/build/MAD-Designer-macOS.dmgPublic user and developer documentation for the native macOS application is published in docs/macos.md (with screenshots at docs/assets/macos-native-mad-query.png and docs/assets/macos-native-mad-designer.png) and Mac/README.md.
.github/workflows/macos.yml runs on every pull request and push to master.
It builds (and caches) the Compressor static libraries, then runs the
MADBarcodes and MAD suites on an iPhone simulator discovered from the
runner, builds the iOS MAD Designer scheme, and runs
./Mac/build.sh --smoke-test. The About window reports the engine version
(MADMeta.plist, v9.0 (r4433)) and the macOS application version
(CFBundleShortVersionString, v0.7) as distinct values, matching the
Windows About window’s post-Phase-6f presentation.
macos-latest is an arm64 runner, and Mac/build.sh builds the frameworks for
platform=macOS,arch=arm64. The first run downloads and compiles every pinned
third-party source for three platforms (roughly 15–40 minutes); later runs
restore Compressor/library from the Actions cache and the ensure step no-ops.
The freetds recipe fetches config.guess/config.sub from Savannah once with
no retry, so the workflow seeds Compressor/media first (see the workflow’s
comments). A residual, not a build failure: libarchive’s configure step found
the SDK’s libbz2.tbd rather than the Compressor bzip2 install, because
BZIP2_LIBRARY is not the hint modern CMake’s FindBZIP2 reads; the SDK
library is present and the app processes the bzip2 xcframework.