MAD_MACOS.md——多平台框架与原生 macOS 应用本页记录多平台框架审计与原生 macOS 应用架构。面向用户的指南位于 /macos.html。
撰写于原定日期;当前状态事实已于 2026-11-22 核实。
本文档记录架构决策、逐框架的可移植性审计,以及分阶段的迁移与实现计划——让 MAD 框架
真正多平台(iphoneos、iphonesimulator、macosx 和无头 Linux),
并为 MAD Designer 构建原生 macOS(AppKit)前端。
AppKit)还是 Mac Catalyst决策: 在共享的多平台框架之上构建原生 macOS 应用(macosx SDK、AppKit)
(MACOSX_DEPLOYMENT_TARGET = 12.0,支持所有 Apple
Silicon Mac 以及运行 Monterey 或更新版本的 Intel Mac)。否决 Mac Catalyst。
| 维度 | 原生 macOS(macosx / AppKit) |
Mac Catalyst(maccatalyst / UIKit) |
|---|---|---|
静态 C 库(Compressor) |
已构建。 Compressor/library/ 中全部 10 个 .xcframework 包都带有通用 macosx(arm64 + x86_64、-mmacosx-version-min=11.0)切片,已由 ./Compressor/build.sh --verify --all --platforms ios,simulator,macosx 验证。 |
缺失。 不存在任何 maccatalyst 切片(-target <arch>-apple-ios15.0-macabi)。Mach-O 链接器拒绝把 MACOS 归档链接进 MACCATALYST 二进制文件;Catalyst 需要给 Compressor 增加第 4 个平台并重新构建全部 10 个 C 库(openssl、mariadb、postgres、freetds、libarchive、sqlite3、zint、libpng、bzip2、zlib)。 |
| 核心引擎可移植性 | 已完成 90%。 Linux 无头移植(MAD_LINUX.md)已从 MAD.framework 移除 Core Data,解耦了数据库驱动(MADDatabaseDriverRegistry)和报表导出器(MADReportExporterRegistry),并引入了 MADHeadlessDocument、MADSQLQueryCompiler 和 MADDesignerLayout。 |
同样的引擎,但受 UIDocument 和 iOS 后台任务生命周期束缚。 |
| 桌面人体工学 | 原生 NSDocument / NSDocumentController(Finder 双击、Cmd+N、Cmd+O、Cmd+S、Cmd+Shift+S、最近文档、窗口恢复、NSUndoManager)、原生分栏视图、原生表/大纲视图、原生 PDFView / WKWebView,以及标准 macOS 菜单。 |
嵌套缩放的 UIScrollView + UICollectionView 带区、iOS 标签/导航栏、UIPickerView 滚轮,以及 iOS 沙盒文档浏览器(MADExplorer)。Apple Silicon Mac 已通过 Designed for iPad 运行 iPad 构建。 |
| 通过 GitHub 分发 | 干净的独立 .app 包,打包为 GitHub Releases 上可下载的 .dmg 和 .zip(arm64 + x86_64)。 |
需要 Catalyst 描述文件和 entitlement,与 App Store 之外的分发人体工学不匹配。 |
Compressor)Compressor 中全部十个 vendored C 库都用 -mmacosx-version-min=11.0 构建通用 macosx(arm64 + x86_64)
切片:
| 库 | 版本 | ios(arm64) |
simulator(arm64 + x86_64) |
macosx(arm64 + x86_64) |
使用者 |
|---|---|---|---|---|---|
sqlite3 |
3.53.3 | 是 | 是 | 是 | MADSqlite3、MAD |
zlib |
1.3.2 | 是 | 是 | 是 | MAD、MADMySQL、MADPostgres、MADBarcodes |
openssl |
3.5.9 | 是 | 是 | 是 | MADTds、MADMySQL、MADPostgres |
bzip2 |
1.0.8 | 是 | 是 | 是 | MAD |
libpng |
1.6.59 | 是 | 是 | 是 | MADBarcodes |
libarchive |
3.8.9 | 是 | 是 | 是 | MAD |
freetds |
1.4.27 | 是 | 是 | 是 | MADTds、MADTdsClient |
mariadb |
3.4.11 | 是 | 是 | 是 | MADMySQL |
postgres |
17.11 | 是 | 是 | 是 | MADPostgres |
zint |
2.16.0 | 是 | 是 | 是 | MADBarcodes |
验证命令:
./Compressor/build.sh --verify --all --platforms ios,simulator,macosx
十二个框架构成多平台技术栈(iphoneos、iphonesimulator、macosx,
外加 Linux 作为十二个无头框架的第十二个平台):
MADFoundation(28 个 .m 文件):
MADApplication.h:用 #if TARGET_OS_IPHONE 而不是 #if __APPLE__ 保护 <UIKit/UIApplication.h>
(MADApplication.m 已有
#elif TARGET_OS_OSX #import <AppKit/NSApplication.h>)。MADURLFactory.m:用 #if TARGET_OS_IPHONE 保护 <UIKit/UIScreen.h>,并在
TARGET_OS_OSX 上使用 NSScreen.mainScreen.backingScaleFactor > 1.0。MADKeyChain.m:使用 Security.framework,它在 iOS 和 macOS 上都是原生的。MADDataStructures(17 个 .m 文件):
MADFileManager(11 个 .m 文件):
MADMetaDataLocal.m:16 中未使用的 #import <MobileCoreServices/UTType.h>
(第 17 行已导入 <UniformTypeIdentifiers/UTType.h>)。MADCocoaExtensions(17 个 .m 文件):
CGGeometry+Extras.h:在 TARGET_OS_OSX 上提供 UIEdgeInsets(与 NSEdgeInsets 兼容的布局
结构体 + UIEdgeInsetsMake / UIEdgeInsetsZero / UIEdgeInsetsEqualToEdgeInsets)、
NSStringFromCGPoint / NSStringFromCGSize / NSStringFromCGRect,以及
NSValue (MADCGGeometryExtensions)(valueWithCGPoint:、CGPointValue、
valueWithCGRect:、CGRectValue、valueWithCGSize:、CGSizeValue)。MADColor.h / MADColor.m:在 TARGET_OS_OSX 上把 MADColor 桥接到 NSColor,同时
在 TARGET_OS_IPHONE 上保留 UIColor。#if TARGET_OS_IPHONE 保护仅 iOS 的 UIView、UIAlertController、UITextField 和 UIColor
category。MADAPI(11 个 .m 文件):
#if TARGET_OS_IPHONE 保护 MADConnectionViewController 和 MADConnectionSQLGenericViewController。MADSqlite3(26 个 .m 文件):
sqlite3.xcframework。无需源码改动。MADTds(1 个 .m 文件):
freetds.xcframework + openssl.xcframework。无需源码
改动。MADTdsClient(4 个 .m 文件):
MADDatabaseSQLServer、MADTdsConnection 和 MADDataTypeSQLServer 是纯
Foundation。用 #if TARGET_OS_IPHONE 保护 MADTdsConnectionViewController。MADMySQL(19 个 .m 文件):
mariadb.xcframework。用
#if TARGET_OS_IPHONE 保护 MADMySQLConnectionViewController。MADPostgres(5 个 .m 文件):
postgres.xcframework。用
#if TARGET_OS_IPHONE 保护 MADPostgresConnectionViewController。MADBarcodes(70 个 .m 文件):
zint.xcframework。MADBarcode、MADBarcodeCache 和 MADBarcodeView:在 TARGET_OS_OSX 上
基于既有的 CGImageRef MADBarcodeImageFromZintBitmap 管线桥接 UIImage / NSImage
和 UIView / NSView。MAD(199 个 .m 文件):
RptqObject.m、
RptqDocumentElementImage+Extras.m、RptqDocument+Extras.m、
RptqDocumentSection+Extras.m、RptqDocumentElement+Extras.m、
MADPrintPageElement.m、MADElementStylizedText.m、MADFonts.m 和
MADReportExporterPDF.m)中,把 #if __APPLE__ 替换为 #if TARGET_OS_IPHONE,并用 #elif TARGET_OS_OSX
AppKit 桥接。MADReportExporterPDF.m 中,在 TARGET_OS_OSX 上使用
CGPDFContextCreateWithURL / CGPDFConsumerCreateWithCFData 和
NSGraphicsContext(+graphicsContextWithCGContext:flipped:YES)渲染分页 PDF,使
MADPrintPageRenderer 和 MADPrintPageElement 在 macOS 上原生绘制。#if TARGET_OS_IPHONE 保护 22 个仅 iOS 的 UIDocument(MADocument)、UIView 和
UICollectionViewLayout 文件。MADExplorer 仍仅限 iOS(macOS 使用 NSDocumentController、Finder 和 NSOpenPanel,并带一个主 New Document 按钮)。MADFeedback 和 Scrimpter 按
AGENTS.md 保持未使用。
docs/project/registers/BUGS.md 归档到 docs/project/registers/BUGS_FIXED.md:
MADKeyChain(MADFoundation/Source/MADKeyChain.m):在
+credentialsExist:、+saveToken:forKey:withDescription:、+deleteKey: 和
+deleteSavedPasswordForKey:error: 中停止请求 kSecReturnData : @YES(并停止泄漏返回的 CFDataRef)。MADURLFactory(MADFoundation/Source/MADURLFactory.m):在 [NSBundle mainBundle].bundleIdentifier
为 nil 时保护 +newURLForLocalApplicationSupportDirectory
(回退到 [MADApplication groupIdentifier]),并用
#if defined(__APPLE__) && TARGET_OS_IPHONE 保护
containerURLForSecurityApplicationGroupIdentifier:,使无 entitlement 的 macOS 进程使用
标准的每用户目录,而不是在
~/Library/Group Containers/ 上触发 TCC 提示。MADDataTable(MADFoundation/Source/MADDataTable.m):用
#if defined(__APPLE__) && TARGET_OS_IPHONE 保护
NSDataWritingFileProtectionCompleteUnlessOpen,使无 entitlement 的 macOS 缓存写入成功。MADDatabaseSqlite3(MADSqlite3/Source/MADDatabaseSqlite3.m):用
if (rowCounter > 0) 保护 [dataTable endBulkInsert],使零行的 SELECT 查询
在 [dataTable beginBulkInsert] 从未被调用时不执行 COMMIT TRANSACTION。MADBarcode(MADBarcodes/MADBarcodes/MADBarcodes/MADBarcode.m):修复了
-drawInRect: 在 self.center == YES 时把 rect.origin 加倍的问题。MADDesignerLayout(MAD/Source/MADDesignerLayout.m):在所有
批量更新方法(setFontsize:、setFontname:、setVerticalAlignment:、
setHorizontalAlignment:、setSizeWidth:、setSizeHeight:、setMargin*、
setPadding*、setBorder*)中注册撤销操作时,把每个选中元素自身的先前值保留在字典中。macosx:
SUPPORTED_PLATFORMS = "iphoneos iphonesimulator macosx" 和
MACOSX_DEPLOYMENT_TARGET = 12.0。UIKit.framework 引用上添加 platformFilters = (ios, maccatalyst, );,并在需要处
以 platformFilters = (macos, ); 链接 AppKit.framework。Ensure Libraries 构建阶段以传入
--platforms ios,simulator,macosx。-destination 'platform=macOS,arch=arm64'):
MADFoundation:199 个测试通过,0 个失败MADDataStructures:72 个测试通过,0 个失败MADCocoaExtensions:80 个测试通过,0 个失败MADFileManager:85 个测试通过,0 个失败MADAPI:106 个测试通过,0 个失败MADSqlite3:118 个测试通过(5 个基准跳过),0 个失败MADTds:为 macosx 干净构建MADTdsClient:77 个测试通过(包括实时 SQL Server 套件),0 个失败MADMySQL:所有离线和实时 MariaDB/MySQL 测试通过,0 个失败MADPostgres:31 个测试通过(包括实时 PostgreSQL 套件),0 个失败MADBarcodes:30 个测试通过,0 个失败MAD:650 个测试通过,0 个失败NSDocument 层(已完成)MADHeadlessDocument):
MADHeadlessDocument(MAD/Source/MADHeadlessDocument.h、.m)上添加了
+createDocumentAtURL:withDatabaseConnection:credentials:error:,它连接到
任何已注册驱动(SQLite3、MySQL、SQL Server、PostgreSQL),把所有
数据库表(-getTablesFromConnection:error:)和列
(-fieldsForTable:connection:error:)导入 RptqDatabaseSchemaTable /
RptqDatabaseSchemaField,初始化标准报表带区(Report Header、
Page Header、Report Detail、Page Footer、Report Footer),并写出
可移植的 .mad 容器。MADMacDocument(Mac/Source/MADMacDocument.m 中的 NSDocument 子类):
MADHeadlessDocument(需要时通过
MADStoreConverter 自动转换遗留 Core Data .mad),遵循 MADocumentDesignerProtocol,使
MADDesignerLayout 把撤销/重做直接记录到 NSDocument.undoManager,并
支持 readFromURL:ofType:error:、
writeToURL:ofType:forSaveOperation:originalContentsURL:error: 以及异步
refreshWithCredentials:maxRows:completion:。Mac/)(已完成)构建于 Mac/ 下(Mac/Source/、Mac/Resources/、Mac/Tests/、Mac/build.sh),并通过 MAD Designer Mac 目标与共享 scheme 集成进 MAD Designer.xcodeproj:
MADMacAppDelegate、MADMacAboutWindowController 和 MADMacDocumentController):
MADStoreLegacyConverter,构建原生 macOS 主菜单(MAD Designer、File、带 Undo/Redo 的 Edit、切换工作区的 View Cmd+1/Cmd+2/Cmd+3、刷新报表的 Report Cmd+R、Window、Help),并在启动时若无打开文档则呈现标准 NSOpenPanel。MADMacAboutWindowController 呈现原生 About MAD Designer 窗口(MAD Designer → About MAD Designer 和 Help 菜单项),分别显示引擎版本/构建(MADMeta.plist)和 macOS 应用版本(CFBundleShortVersionString),以及版权和保留的品牌/美术资源声明、Source Code on GitHub 操作,以及三个标签页:Overview(MAD 是什么、4 步报表工作流,以及支持的驱动/带区/导出器)、License & Notice(MIT License、NOTICE,以及针对 FreeTDS 和 MariaDB Connector/C 的 LGPL-3.0 书面重新链接要约)和 Acknowledgements(全部 16 个第三方开源组件的交互式侧栏,配有其归属说明,以及打包在 Contents/Resources/Licenses/ 下的 12 份完整许可证文本)。MADMacDocumentController 为 NSOpenPanel 配置全部 .mad UTType 标识符(com.everydayapps.productivity.mad 和 com.thomason.report.mad),使已有 .mad 文件永不被置灰,并在打开面板左下栏直接放置一个主 New Document 按钮。MADMacConnectionWindowController):
NSOpenPanel 选择自定义 .sqlite3/.db 文件)、MySQL、Microsoft SQL Server 和 PostgreSQL,带 Test Connection、MADKeyChain 密码存储,以及 Create Document…(NSSavePanel)。MADMacWindowController):
MADMacQueryViewController):
200px 的左侧 Database Tables 列表(可通过 NSSplitViewDelegate 由用户调整大小且不会回弹,且在调整窗口大小时保持固定宽度,使可视化画布随之缩放),配以一个交互式
右侧可视化画布(MADMacQueryCanvasView)。双击架构表
把它加入查询(填充所有 RptqQueryField 行),并将其显示为
可拖动、可调整大小的浮动 AppKit 表卡片(MADMacQueryTableCardView +
MADMacQueryFieldTableView),以拓扑根/子头部(MTGraph)样式呈现,
且从一张表卡片的字段拖到另一张表卡片的字段会创建默认的
Left Outer Join(MADLinkTypeLeftOuterJoin),经由 Bezier 连接线和
联接类型徽标绘制(MADMacQueryLinksOverlayView,与 iPad 的 MADConnectorView 一致)。
单击或右键单击可视化联接连接线会打开联接检查器浮出或
上下文菜单,以更改联接类型、交换方向或删除联接;头部
浮出提供 Filters (WHERE)、Groupings (GROUP BY) 和 Arrange Tables。MADSQLParser +
MADSQLStatementResolver + MADSQLQueryCompiler)。MADMacDesignerViewController + MADMacDesignerCanvasView + MADMacDesignerMinimapView):
38pt 高): 提供可单击且可拖动的 SF Symbol
元素调色板项(Label、Data Field、Aggregate、Barcode、
Image、Line)、快速多元素对齐控件(Left、Center、
Right、Top、Middle、Bottom)、Size to Fit、Grid / Snap /
Rulers 开关,以及带一键 100% 复位的 Zoom 滑块。NSSplitViewDelegate): 左导航侧栏
默认 220pt(180–340pt),右检查器默认 260pt
(220–380pt),两个侧栏在窗口调整大小时保持宽度,同时
保留用户的分隔条调整。MADMacDesignerMinimapView): 按比例绘制
报表带区,带颜色编码条纹、实时微型元素块,
以及一个蓝色视口矩形;单击或拖动会跳转并选中该带区。RptqQueryField
列的可过滤列表(NSSearchField);把字段拖到画布上任何带区带(或双击)
会插入一个绑定的 RptqDocumentElementLabelDataField。MADMacDesignerCanvasView): 翻转、可缩放的
NSView 画布,带水平/垂直标尺、纸张边距、颜色编码的带区
带、带区高度拖动手柄、智能对齐参考线、网格吸附、框选
选择、Shift-单击多选、8 点调整大小手柄、内联双击
标签编辑、智能非重叠元素放置
(-nextAvailableOriginInSection:forElementSize:),以及跨带区拖放
(-moveElement:toSection:atOrigin:),带实时目标带区高亮和完整
NSUndoManager 集成。1 · PAGE & SELECTED SECTION): 纸张尺寸、选中带区徽标、
带区高度(pt)及 Fit Height 按钮、Section Visible,以及 Page Break
After。2 · SELECTED ELEMENT INSPECTOR):
4 张分组检查器卡片(Element & Band Assignment,带跨带区移动
弹出、Duplicate 和 Delete;Content & Data Binding,带静态文本、
查询字段绑定、聚合函数与范围、货币格式和条形码
选项;Typography & Appearance,带字族/字号、粗体/斜体/下划线/
删除线、水平/垂直对齐和文本/背景颜色;以及
Position, Size & Box Model,带 X、Y、W、H,在
rect.origin 和 dropPoint 间同步,另有边框、内边距和外边距)。MADMacViewerViewController):
40pt 高): Page Size 弹出(MTPaper 标准纸张类型:US Letter、US Legal、US Tabloid、A3、A4、A5、B4、B5、JIS B4、JIS B5)、Refresh(Cmd+R)、Zoom 控件(-、100%、+)、Page Navigation(Previous、Page N of M、Next)、Print…(Cmd+P,经由 NSPrintOperation)和 Export…(Cmd+E)。PDFView): 从本地 SQLite 表缓存(MADDataTableFast)按选定纸张尺寸渲染分页 PDF 页面,带页面阴影和底部状态栏(statusBarView),显示已渲染页数、缓存行数和纸张尺寸。NSSavePanel): 配置一个附件格式弹出,支持全部 7 个已注册导出器(PDF、HTML、HTML Flow、CSV、JSON、JSON Report、Plain Text),并动态更新保存面板的允许文件扩展名。./Mac/build.sh --smoke-test --package
产出:
Mac/build/MAD Designer.app(独立原生 macOS 应用包,内嵌并签名全部 12 个
框架和遗留 Core Data .momd 模型)Mac/build/MAD-Designer-macOS.zipMac/build/MAD-Designer-macOS.dmg原生 macOS 应用的公开用户与开发者文档发布在 docs/macos.md(截图位于 docs/assets/macos-native-mad-query.png 和 docs/assets/macos-native-mad-designer.png)以及 Mac/README.md。
.github/workflows/macos.yml 在每次拉取请求和推送到 master 时运行。
它构建(并缓存)Compressor 静态库,然后在从
运行器发现的 iPhone 模拟器上运行 MADBarcodes 和 MAD 套件,构建 iOS MAD Designer scheme,并运行
./Mac/build.sh --smoke-test。“关于”窗口把引擎版本
(MADMeta.plist,v9.0 (r4433))和 macOS 应用版本
(CFBundleShortVersionString,v0.7)作为不同的值分别报告,与
Windows“关于”窗口在 Phase-6f 之后的呈现一致。
macos-latest 是 arm64 运行器,Mac/build.sh 为
platform=macOS,arch=arm64 构建框架。首次运行会下载并编译每个锁定的
第三方来源(针对三个平台,约 15–40 分钟);之后的运行
从 Actions 缓存恢复 Compressor/library,ensure 步骤则空操作。
freetds 配方从 Savannah 获取 config.guess/config.sub 一次且
不重试,因此工作流会先播种 Compressor/media(参见该工作流的
注释)。一处残余,而非构建失败:libarchive 的 configure 步骤找到的是
SDK 的 libbz2.tbd,而非 Compressor 的 bzip2 安装,因为
BZIP2_LIBRARY 不是现代 CMake 的 FindBZIP2 所读取的提示;SDK
库存在,应用处理 bzip2 xcframework。
本页为英文原文的简体中文翻译;如有出入,以英文原文为准。