MAD_MACOS.md – Frameworks multiplataforma e o aplicativo nativo para macOSEsta página registra a auditoria dos frameworks multiplataforma e a arquitetura do aplicativo nativo para macOS. O guia voltado ao usuário está em /macos.html.
Escrito na data original; fatos do estado atual reconciliados em 2026-11-22.
Este documento registra a decisão de arquitetura, a auditoria de portabilidade framework por framework
e o plano faseado de migração e implementação para tornar os frameworks MAD
genuinamente multiplataforma (iphoneos, iphonesimulator, macosx e Linux headless)
e construir o frontend nativo para macOS (AppKit) do MAD Designer.
AppKit) vs. Mac CatalystDecisão: construir um aplicativo nativo para macOS (SDK macosx, AppKit) sobre frameworks
multiplataforma compartilhados (MACOSX_DEPLOYMENT_TARGET = 12.0, com suporte a todo Mac Apple
Silicon e a Macs Intel no Monterey ou mais recente). O Mac Catalyst é rejeitado.
| Dimensão | macOS nativo (macosx / AppKit) |
Mac Catalyst (maccatalyst / UIKit) |
|---|---|---|
Bibliotecas C estáticas (Compressor) |
Já compiladas. Todos os 10 pacotes .xcframework em Compressor/library/ carregam fatias universais macosx (arm64 + x86_64, -mmacosx-version-min=11.0) verificadas por ./Compressor/build.sh --verify --all --platforms ios,simulator,macosx. |
Ausentes. Não existe nenhuma fatia maccatalyst (-target <arch>-apple-ios15.0-macabi). O linker Mach-O rejeita vincular arquivos MACOS em binários MACCATALYST; o Catalyst exigiria adicionar uma 4ª plataforma ao Compressor e recompilar todas as 10 bibliotecas C (openssl, mariadb, postgres, freetds, libarchive, sqlite3, zint, libpng, bzip2, zlib). |
| Portabilidade do núcleo da engine | 90% concluída. A portabilidade headless para Linux (MAD_LINUX.md) já removeu o Core Data do MAD.framework, desacoplou os drivers de banco de dados (MADDatabaseDriverRegistry) e os exportadores de relatórios (MADReportExporterRegistry), e introduziu MADHeadlessDocument, MADSQLQueryCompiler e MADDesignerLayout. |
A mesma engine, mas presa aos ciclos de vida de UIDocument e de tarefas em segundo plano do iOS. |
| Ergonomia de desktop | NSDocument / NSDocumentController nativos (duplo clique no Finder, Cmd+N, Cmd+O, Cmd+S, Cmd+Shift+S, Documentos Recentes, restauração de janela, NSUndoManager), visões divididas nativas, visões de tabela/estrutura nativas, PDFView / WKWebView nativos e menus padrão do macOS. |
UIScrollView + seções UICollectionView com zoom aninhado, barras de abas/navegação do iOS, rodas UIPickerView e navegador de documentos em sandbox do iOS (MADExplorer). Macs Apple Silicon já executam a compilação para iPad via Designed for iPad. |
| Distribuição via GitHub | Pacote .app independente e limpo, empacotado como .dmg e .zip para download no GitHub Releases (arm64 + x86_64). |
Exige perfil de provisionamento e direitos do Catalyst que não combinam com a ergonomia de distribuição fora da App Store. |
Compressor)Todas as dez bibliotecas C fornecidas em Compressor compilam fatias universais macosx (arm64 + x86_64)
com -mmacosx-version-min=11.0:
| Biblioteca | Versão | ios (arm64) |
simulator (arm64 + x86_64) |
macosx (arm64 + x86_64) |
Usada por |
|---|---|---|---|---|---|
sqlite3 |
3.53.3 | Sim | Sim | Sim | MADSqlite3, MAD |
zlib |
1.3.2 | Sim | Sim | Sim | MAD, MADMySQL, MADPostgres, MADBarcodes |
openssl |
3.5.9 | Sim | Sim | Sim | MADTds, MADMySQL, MADPostgres |
bzip2 |
1.0.8 | Sim | Sim | Sim | MAD |
libpng |
1.6.59 | Sim | Sim | Sim | MADBarcodes |
libarchive |
3.8.9 | Sim | Sim | Sim | MAD |
freetds |
1.4.27 | Sim | Sim | Sim | MADTds, MADTdsClient |
mariadb |
3.4.11 | Sim | Sim | Sim | MADMySQL |
postgres |
17.11 | Sim | Sim | Sim | MADPostgres |
zint |
2.16.0 | Sim | Sim | Sim | MADBarcodes |
Comando de verificação:
./Compressor/build.sh --verify --all --platforms ios,simulator,macosx
Doze frameworks formam a pilha multiplataforma (iphoneos, iphonesimulator, macosx,
mais Linux para os doze frameworks headless):
MADFoundation (28 arquivos .m):
MADApplication.h: proteja <UIKit/UIApplication.h> com #if TARGET_OS_IPHONE
em vez de #if __APPLE__ (MADApplication.m já tem
#elif TARGET_OS_OSX #import <AppKit/NSApplication.h>).MADURLFactory.m: proteja <UIKit/UIScreen.h> com #if TARGET_OS_IPHONE e use
NSScreen.mainScreen.backingScaleFactor > 1.0 em TARGET_OS_OSX.MADKeyChain.m: usa Security.framework, que é nativo tanto no iOS quanto no macOS.MADDataStructures (17 arquivos .m):
MADFileManager (11 arquivos .m):
#import <MobileCoreServices/UTType.h> não utilizado em
MADMetaDataLocal.m:16 (<UniformTypeIdentifiers/UTType.h> já está importado na
linha 17).MADCocoaExtensions (17 arquivos .m):
CGGeometry+Extras.h: forneça UIEdgeInsets (struct de layout compatível com NSEdgeInsets
UIEdgeInsetsMake / UIEdgeInsetsZero / UIEdgeInsetsEqualToEdgeInsets),
NSStringFromCGPoint / NSStringFromCGSize / NSStringFromCGRect e
NSValue (MADCGGeometryExtensions) (valueWithCGPoint:, CGPointValue,
valueWithCGRect:, CGRectValue, valueWithCGSize:, CGSizeValue) em
TARGET_OS_OSX.MADColor.h / MADColor.m: faça a ponte de MADColor para NSColor em TARGET_OS_OSX mantendo
UIColor em TARGET_OS_IPHONE.UIView, UIAlertController, UITextField e UIColor, exclusivas do iOS,
com #if TARGET_OS_IPHONE.MADAPI (11 arquivos .m):
MADConnectionViewController e MADConnectionSQLGenericViewController
com #if TARGET_OS_IPHONE.MADSqlite3 (26 arquivos .m):
sqlite3.xcframework. Nenhuma mudança no código-fonte necessária.MADTds (1 arquivo .m):
freetds.xcframework + openssl.xcframework. Nenhuma mudança no código-fonte
necessária.MADTdsClient (4 arquivos .m):
MADDatabaseSQLServer, MADTdsConnection e MADDataTypeSQLServer são
Foundation puro. Proteja MADTdsConnectionViewController com #if TARGET_OS_IPHONE.MADMySQL (19 arquivos .m):
mariadb.xcframework. Proteja
MADMySQLConnectionViewController com #if TARGET_OS_IPHONE.MADPostgres (5 arquivos .m):
postgres.xcframework. Proteja
MADPostgresConnectionViewController com #if TARGET_OS_IPHONE.MADBarcodes (70 arquivos .m):
zint.xcframework.MADBarcode, MADBarcodeCache e MADBarcodeView: faça a ponte de UIImage / NSImage
e UIView / NSView em TARGET_OS_OSX sobre o pipeline existente
MADBarcodeImageFromZintBitmap de CGImageRef.MAD (199 arquivos .m):
#if __APPLE__ por #if TARGET_OS_IPHONE e #elif TARGET_OS_OSX
nas pontes AppKit dos 9 arquivos compartilhados de modelo/renderização (RptqObject.m,
RptqDocumentElementImage+Extras.m, RptqDocument+Extras.m,
RptqDocumentSection+Extras.m, RptqDocumentElement+Extras.m,
MADPrintPageElement.m, MADElementStylizedText.m, MADFonts.m e
MADReportExporterPDF.m).MADReportExporterPDF.m, renderize PDFs paginados em TARGET_OS_OSX usando
CGPDFContextCreateWithURL / CGPDFConsumerCreateWithCFData e
NSGraphicsContext (+graphicsContextWithCGContext:flipped:YES), para que
MADPrintPageRenderer e MADPrintPageElement desenhem nativamente no macOS.UIDocument (MADocument), UIView e
UICollectionViewLayout exclusivos do iOS com #if TARGET_OS_IPHONE.MADExplorer permanece exclusivo do iOS (o macOS usa NSDocumentController, o Finder e NSOpenPanel com um botão New Document primário). MADFeedback e Scrimpter permanecem sem uso conforme
AGENTS.md.
docs/project/registers/BUGS.md para docs/project/registers/BUGS_FIXED.md com testes unitários:
MADKeyChain (MADFoundation/Source/MADKeyChain.m): parou de solicitar
kSecReturnData : @YES (e de vazar o CFDataRef retornado) em
+credentialsExist:, +saveToken:forKey:withDescription:, +deleteKey: e
+deleteSavedPasswordForKey:error:.MADURLFactory (MADFoundation/Source/MADURLFactory.m): protegeu
+newURLForLocalApplicationSupportDirectory quando [NSBundle mainBundle].bundleIdentifier
é nil (recorrendo a [MADApplication groupIdentifier]), e protegeu
containerURLForSecurityApplicationGroupIdentifier: com
#if defined(__APPLE__) && TARGET_OS_IPHONE para que processos macOS sem direitos usem
diretórios padrão por usuário em vez de disparar avisos do TCC em
~/Library/Group Containers/.MADDataTable (MADFoundation/Source/MADDataTable.m): protegeu
NSDataWritingFileProtectionCompleteUnlessOpen com
#if defined(__APPLE__) && TARGET_OS_IPHONE para que gravações de cache no macOS sem direitos tenham sucesso.MADDatabaseSqlite3 (MADSqlite3/Source/MADDatabaseSqlite3.m): protegeu
[dataTable endBulkInsert] com if (rowCounter > 0) para que consultas SELECT com zero linhas
não executem COMMIT TRANSACTION quando [dataTable beginBulkInsert] nunca foi
chamado.MADBarcode (MADBarcodes/MADBarcodes/MADBarcodes/MADBarcode.m): corrigiu
-drawInRect: que duplicava rect.origin quando self.center == YES.MADDesignerLayout (MAD/Source/MADDesignerLayout.m): preservou o valor prévio de cada elemento
selecionado em um dicionário ao registrar ações de desfazer em todos os
métodos de atualização em lote (setFontsize:, setFontname:, setVerticalAlignment:,
setHorizontalAlignment:, setSizeWidth:, setSizeHeight:, setMargin*,
setPadding*, setBorder*).macosx nos 12 projetos Xcode dos frameworks:
SUPPORTED_PLATFORMS = "iphoneos iphonesimulator macosx" e
MACOSX_DEPLOYMENT_TARGET = 12.0.platformFilters = (ios, maccatalyst, ); nas referências a UIKit.framework e
vinculado AppKit.framework com platformFilters = (macos, ); onde necessário.Ensure Libraries para passar
--platforms ios,simulator,macosx.-destination 'platform=macOS,arch=arm64'):
MADFoundation: 199 testes passaram, 0 falhasMADDataStructures: 72 testes passaram, 0 falhasMADCocoaExtensions: 80 testes passaram, 0 falhasMADFileManager: 85 testes passaram, 0 falhasMADAPI: 106 testes passaram, 0 falhasMADSqlite3: 118 testes passaram (5 benchmarks ignorados), 0 falhasMADTds: Compilado sem erros para macosxMADTdsClient: 77 testes passaram (incluindo a suíte ativa do SQL Server), 0 falhasMADMySQL: Todos os testes offline e ativos de MariaDB/MySQL passaram, 0 falhasMADPostgres: 31 testes passaram (incluindo a suíte ativa do PostgreSQL), 0 falhasMADBarcodes: 30 testes passaram, 0 falhasMAD: 650 testes passaram, 0 falhasNSDocument (Concluída)MADHeadlessDocument):
+createDocumentAtURL:withDatabaseConnection:credentials:error: em
MADHeadlessDocument (MAD/Source/MADHeadlessDocument.h, .m), que conecta a
qualquer driver registrado (SQLite3, MySQL, SQL Server, PostgreSQL), importa todas
as tabelas do banco de dados (-getTablesFromConnection:error:) e colunas
(-fieldsForTable:connection:error:) em RptqDatabaseSchemaTable /
RptqDatabaseSchemaField, inicializa as seções padrão do relatório (Report Header,
Page Header, Report Detail, Page Footer, Report Footer) e grava o
contêiner portátil .mad.MADMacDocument (subclasse de NSDocument em Mac/Source/MADMacDocument.m):
MADHeadlessDocument (com conversão automática de .mad legado do Core Data via
MADStoreConverter quando necessário), conforma-se a MADocumentDesignerProtocol para que
MADDesignerLayout registre desfazer/refazer diretamente no NSDocument.undoManager, e
suporta readFromURL:ofType:error:,
writeToURL:ofType:forSaveOperation:originalContentsURL:error: e
refreshWithCredentials:maxRows:completion: assíncrono.Mac/) (Concluída)Construído em Mac/ (Mac/Source/, Mac/Resources/, Mac/Tests/, Mac/build.sh) e integrado ao MAD Designer.xcodeproj pelo alvo MAD Designer Mac e esquema compartilhado:
MADMacAppDelegate, MADMacAboutWindowController e MADMacDocumentController):
MADStoreLegacyConverter, constrói o menu principal nativo do macOS (MAD Designer, File, Edit com Undo/Redo, View alternando áreas de trabalho com Cmd+1/Cmd+2/Cmd+3, Report atualizando com Cmd+R, Window, Help) e apresenta o NSOpenPanel padrão na inicialização quando nenhum documento está aberto.MADMacAboutWindowController apresenta a janela nativa About MAD Designer (itens MAD Designer → About MAD Designer e do menu Help) com a versão/compilação da engine (MADMeta.plist) e a versão do aplicativo macOS (CFBundleShortVersionString) mostradas como valores distintos, aviso de direitos autorais e de marca/arte reservada, ação Source Code on GitHub e três seções em abas: Overview (o que é o MAD, o fluxo de relatórios em 4 passos e drivers/faixas/exportadores suportados), License & Notice (Licença MIT, NOTICE e a oferta escrita de relink LGPL-3.0 para FreeTDS e MariaDB Connector/C) e Acknowledgements (barra lateral interativa de todos os 16 componentes open-source de terceiros com suas atribuições e os 12 textos completos de licença incluídos em Contents/Resources/Licenses/).MADMacDocumentController configura o NSOpenPanel com todos os identificadores UTType de .mad (com.everydayapps.productivity.mad e com.thomason.report.mad) para que arquivos .mad existentes nunca fiquem esmaecidos, e coloca um botão New Document primário diretamente na barra inferior esquerda do painel Abrir.MADMacConnectionWindowController):
.sqlite3/.db personalizado via NSOpenPanel), MySQL, Microsoft SQL Server e PostgreSQL, com Test Connection, armazenamento de senha no MADKeyChain e Create Document… (NSSavePanel).MADMacWindowController):
MADMacQueryViewController):
200px à esquerda (redimensionável pelo usuário
via NSSplitViewDelegate sem voltar ao tamanho anterior, e mantida em largura fixa quando a
janela é redimensionada para que a tela visual seja redimensionada) emparelhada com uma tela visual
interativa à direita (MADMacQueryCanvasView). Um duplo clique em uma tabela de esquema
a adiciona à consulta (preenchendo todas as linhas RptqQueryField) e a exibe como um
cartão de tabela AppKit flutuante arrastável e redimensionável (MADMacQueryTableCardView +
MADMacQueryFieldTableView) estilizado com cabeçalhos topológicos de raiz/filho (MTGraph),
e arrastar de um campo em um cartão de tabela para um campo em outro cria uma
Left Outer Join padrão (MADLinkTypeLeftOuterJoin) desenhada com conectores Bezier e
emblemas de tipo de junção (MADMacQueryLinksOverlayView, correspondendo ao MADConnectorView do iPad).
Clicar ou clicar com o botão direito em um conector de junção visual abre um popover de inspetor de junção ou
menu de contexto para mudar o tipo de link, inverter a direção ou excluir o link; popovers de cabeçalho
fornecem Filters (WHERE), Groupings (GROUP BY) e Arrange Tables.MADSQLParser +
MADSQLStatementResolver + MADSQLQueryCompiler).MADMacDesignerViewController + MADMacDesignerCanvasView + MADMacDesignerMinimapView):
38pt): fornece itens de paleta de elementos SF Symbol clicáveis e arrastáveis
(Label, Data Field, Aggregate, Barcode,
Image, Line), controles rápidos de alinhamento de vários elementos (Left, Center,
Right, Top, Middle, Bottom), Size to Fit, alternadores Grid / Snap /
Rulers e um controle deslizante Zoom com redefinição para 100% em um clique.NSSplitViewDelegate): a barra lateral de navegação esquerda
tem padrão de 220pt (180–340pt), o inspetor direito tem padrão de 260pt
(220–380pt), e ambas as barras laterais mantêm suas larguras ao redimensionar a janela enquanto
preservam os ajustes de divisória do usuário.MADMacDesignerMinimapView): desenha
faixas proporcionais do relatório com listras codificadas por cor, blocos em miniatura ao vivo dos elementos
e um retângulo de visão azul; clicar ou arrastar salta para a faixa e a seleciona.NSSearchField) de todas as colunas
RptqQueryField; arrastar um campo para qualquer faixa de seção na tela (ou um duplo clique)
insere um RptqDocumentElementLabelDataField vinculado.MADMacDesignerCanvasView): tela NSView invertida e ampliável
com réguas horizontais/verticais, margens de papel, faixas de seção codificadas por cor,
alças de arraste de altura de seção, guias de alinhamento inteligentes, encaixe na grade, seleção
por retângulo, seleção múltipla com Shift+clique, alças de redimensionamento em 8 pontos, edição de rótulo
em linha com duplo clique, posicionamento inteligente de elementos sem sobreposição
(-nextAvailableOriginInSection:forElementSize:) e arrastar e soltar entre seções
(-moveElement:toSection:atOrigin:) com realce ao vivo da faixa de destino e integração
completa com NSUndoManager.1 · PAGE & SELECTED SECTION): tamanho do papel, emblema da faixa selecionada,
altura da faixa (pt) com botão Fit Height, Section Visible e Page Break
After.2 · SELECTED ELEMENT INSPECTOR):
4 cartões de inspetor agrupados (Element & Band Assignment com popup de movimentação entre seções,
Duplicate e Delete; Content & Data Binding com texto estático,
vinculação de campo de consulta, função e escopo de agregado, formatação de moeda e opções
de código de barras; Typography & Appearance com família/tamanho de fonte, negrito/itálico/sublinhado/
tachado, alinhamento horizontal/vertical e cores de texto/fundo; e
Position, Size & Box Model com X, Y, W, H sincronizados entre
rect.origin e dropPoint, mais bordas, preenchimento e margem).MADMacViewerViewController):
40pt): popup Page Size (tipos de papel padrão
MTPaper: US Letter, US Legal, US Tabloid, A3, A4, A5, B4, B5, JIS B4, JIS B5), Refresh (Cmd+R), controles de Zoom
(-, 100%, +), Page Navigation (Previous, Page N of M, Next), Print…
(Cmd+P via NSPrintOperation) e Export… (Cmd+E).PDFView): renderiza páginas PDF paginadas no tamanho de papel
selecionado a partir do cache local da tabela SQLite (MADDataTableFast) com sombras de página e uma
barra de status inferior (statusBarView) exibindo a contagem de páginas renderizadas, a contagem de linhas em cache
e as dimensões do papel.NSSavePanel): configura um popup de formato acessório que suporta todos os 7
exportadores registrados (PDF, HTML, HTML Flow, CSV, JSON, JSON Report, Plain Text) e
atualiza dinamicamente a extensão de arquivo permitida no painel de salvamento../Mac/build.sh --smoke-test --package
Produz:
Mac/build/MAD Designer.app (pacote de aplicativo macOS nativo independente com todos os 12
frameworks e modelos .momd legados do Core Data embutidos e assinados)Mac/build/MAD-Designer-macOS.zipMac/build/MAD-Designer-macOS.dmgA documentação pública de usuário e desenvolvedor do aplicativo nativo para macOS é publicada em docs/macos.md (com capturas de tela em docs/assets/macos-native-mad-query.png e docs/assets/macos-native-mad-designer.png) e em Mac/README.md.
.github/workflows/macos.yml é executado em cada pull request e push para master.
Ele compila (e armazena em cache) as bibliotecas estáticas do Compressor, depois executa as
suítes MADBarcodes e MAD em um simulador de iPhone descoberto no
runner, compila o esquema iOS MAD Designer e executa
./Mac/build.sh --smoke-test. A janela Sobre relata a versão da engine
(MADMeta.plist, v9.0 (r4433)) e a versão do aplicativo macOS
(CFBundleShortVersionString, v0.7) como valores distintos, correspondendo à
apresentação pós-Fase-6f da janela Sobre do Windows.
macos-latest é um runner arm64, e Mac/build.sh compila os frameworks para
platform=macOS,arch=arm64. A primeira execução baixa e compila todo código-fonte
de terceiros fixado para três plataformas (cerca de 15–40 minutos); execuções posteriores
restauram Compressor/library do cache do Actions e o passo de garantia não faz nada.
A receita do freetds busca config.guess/config.sub do Savannah uma vez sem
nova tentativa, então o workflow semeia Compressor/media primeiro (veja os comentários
do workflow). Um resíduo, não uma falha de compilação: o passo configure do libarchive encontrou
o libbz2.tbd do SDK em vez da instalação do bzip2 do Compressor, porque
BZIP2_LIBRARY não é a dica que o FindBZIP2 do CMake moderno lê; a biblioteca do SDK
está presente e o aplicativo processa o xcframework do bzip2.
Esta página é uma tradução para o português do Brasil do original em inglês; em caso de divergência, prevalece a versão original em inglês.