macOS Guia da Plataforma

O backend macOS usa Cocoa/AppKit (Objective-C++) para todos os componentes nativos de UI. Ele fornece uma experiencia Mac autentica com widgets nativos, suporte ao modo escuro via NSAppearanceNameDarkAqua, e integracao completa com o sistema de janelas do macOS.

Visao Geral da Arquitetura

Criacao de Janelas Nativas

Cada formulario HarbourBuilder e um NSWindow nativo com uma visao de conteudo NSView. Controles sao subclasses Cocoa de NSView:

// cocoa_backend.mm - Criando uma janela de formulario
HB_FUNC( UI_FORMNEW )
{
   const char * cTitle = hb_parc( 1 );
   NSInteger nWidth  = hb_parni( 2 );
   NSInteger nHeight = hb_parni( 3 );

   NSRect frame = NSMakeRect( 0, 0, nWidth, nHeight );
   NSWindowStyleMask style = NSWindowStyleMaskTitled |
                             NSWindowStyleMaskClosable |
                             NSWindowStyleMaskMiniaturizable |
                             NSWindowStyleMaskResizable;

   NSWindow * window = [[NSWindow alloc] initWithContentRect:frame
                                                    styleMask:style
                                                      backing:NSBackingStoreBuffered
                                                        defer:NO];
   [window setTitle:[NSString stringWithUTF8String:cTitle]];
   [window center];

   // Configurar a visao de conteudo (NSView para controles filhos)
   NSView * contentView = [[NSView alloc] initWithFrame:frame];
   [window setContentView:contentView];

   // Armazenar handle na tabela de objetos do lado Harbour
   hb_retnint( (NSInteger)(intptr_t) window );
}

Controles mapeiam para classes Cocoa nativas:

Tratamento de Eventos

O backend macOS usa o padrao target-action do Cocoa e o sistema de notificacoes. Cada controle registra um target de acao que chama o sistema de eventos Harbour:

// cocoa_backend.mm - Vinculacao de eventos de botao
HB_FUNC( UI_ONEVENT )
{
   NSInteger nHandle = hb_parnint( 1 );
   NSInteger nEventId = hb_parnint( 2 );
   PHB_ITEM pBlock = hb_param( 3, HB_IT_BLOCK );

   NSButton * btn = (NSButton *)(intptr_t) nHandle;

   // Armazenar o bloco de codigo Harbour em uma tabela lateral
   StoreEventBlock( nHandle, nEventId, pBlock );

   // Configurar o target-action Cocoa
   EventTarget * target = [[EventTarget alloc] initWithHandle:nHandle eventId:nEventId];
   [btn setTarget:target];
   [btn setAction:@selector( fire: )];
}

// EventTarget aciona o bloco de codigo Harbour
@implementation EventTarget
- (void) fire:(id)sender {
   FireEvent( self.handle, self.eventId );
}
@end

Modo Escuro

O modo escuro do macOS e gerenciado nativamente pelo AppKit:

• NSAppearanceNameDarkAqua — O backend define a aparencia da aplicacao como NSAppearanceNameDarkAqua quando o sistema esta em modo escuro. Todos os controles Cocoa padrao adaptam automaticamente suas cores.
• Cores automaticas de controles — NSColor fornece cores semanticas (labelColor, controlColor, windowBackgroundColor) que alternam automaticamente entre variantes claras e escuras.
• Observacao do tema do sistema — O backend registra para NSApplicationDidChangeScreenParametersNotification para detetar mudancas de tema em tempo de execucao.

Integracao Scintilla

No macOS, Scintilla 5.5.3 e compilado como biblioteca estatica e linkado diretamente no binario do HarbourBuilder:

Processo de Build

Pre-requisitos

1. Xcode Command Line Tools — Este e o unico pre-requisito. Instale com:

   xcode-select --install

   Isso fornece clang, make e os headers do SDK macOS.
2. Nenhuma instalacao separada do Harbour necessaria — O script de build baixa e compila o Harbour automaticamente se nao estiver presente.

Script de Build (build_mac.sh)

O script executa estas etapas:

1. Verificar Harbour — Se $HBDIR nao estiver definido ou o Harbour nao for encontrado em ~/harbour, ele clona e compila o Harbour de github.com/harbour/core.
2. Build do Scintilla — Baixa o fonte Scintilla 5.5.3 e compila libscintilla.a e liblexilla.a como bibliotecas estaticas.
3. Compilar o IDE — Compila o fonte do HarbourBuilder usando o compilador Harbour e clang para o backend Objective-C++.
4. Linkagem — Linka com os frameworks macOS: -framework Cocoa, -framework Foundation, -framework AppKit, mais o runtime Harbour e bibliotecas estaticas Scintilla.

# build_mac.sh - Sessao de build tipica
cd HarbourBuilder/samples
./build_mac.sh

# Copiar para bin/ e executar
cp HbBuilder ../bin/
../bin/HbBuilder

Consideracoes Apple Silicon

O build padrao tem como alvo x86_64 para compatibilidade. Em Macs Apple Silicon (M1/M2/M3/M4), o binario roda sob traducao Rosetta 2. Para builds ARM64 nativas:

1. Recompile o Harbour para darwin/clang/arm64
2. Atualize HBDIR em build_mac.sh para apontar para o build ARM64 do Harbour
3. Recompile o Scintilla com -arch arm64
4. Compile o HarbourBuilder com clang -arch arm64

# Build para Apple Silicon (ARM64)
export CFLAGS="-arch arm64"
export LDFLAGS="-arch arm64"
HBDIR=~/harbour_arm64 ./build_mac.sh

Criacao de Pacote .app

Para distribuir uma aplicacao HarbourBuilder como um pacote de aplicacao macOS padrao:

MyApp.app/
├── Contents/
│   ├── Info.plist          // Metadados do pacote
│   ├── MacOS/
│   │   └── MyApp           // O binario compilado
│   ├── Resources/
│   │   ├── icon.icns       // Icone da aplicacao
│   │   └── MainMenu.nib    // (opcional) MainMenu
│   └── PkgInfo             // APPL????

Recursos Especificos da Plataforma

Limitacoes Conhecidas

• Gatekeeper — Aplicacoes nao assinadas podem ser bloqueadas pelo Gatekeeper. Clique direito → Abrir, ou remova a quarentena: xattr -d com.apple.quarantine HbBuilder.
• Notarizacao — Para distribuicao a outros Macs, o binario deve ser notariado pelo programa Developer ID da Apple.
• Versao do Scintilla — O backend macOS usa Scintilla 5.5.3 (vs 5.6.1 no Windows/Linux) devido a requisitos de compatibilidade especificos do Cocoa na versao mais recente.
• ARM64 — Builds nativas Apple Silicon exigem recompilacao manual do Harbour e Scintilla para arm64.

Dependencias