macOS Platform Guide

The macOS backend uses Cocoa/AppKit (Objective-C++) for all native UI components. It provides a true Mac experience with native widgets, dark mode support via NSAppearanceNameDarkAqua, and full integration with the macOS windowing system.

Architecture Overview

Native Window Creation

Every HarbourBuilder form is a native NSWindow with an NSView content view. Controls are Cocoa subclasses of NSView:

// cocoa_backend.mm - Creating a form window
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];

   // Set up the content view (NSView for child controls)
   NSView * contentView = [[NSView alloc] initWithFrame:frame];
   [window setContentView:contentView];

   // Store handle in Harbour-side object table
   hb_retnint( (NSInteger)(intptr_t) window );
}

Controls map to native Cocoa classes:

Event Handling

The macOS backend uses Cocoa's target-action pattern and notification system. Each control registers an action target that calls into the Harbour event system:

// cocoa_backend.mm - Button event binding
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;

   // Store the Harbour code block in a side table
   StoreEventBlock( nHandle, nEventId, pBlock );

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

// EventTarget fires the Harbour code block
@implementation EventTarget
- (void) fire:(id)sender {
   FireEvent( self.handle, self.eventId );
}
@end

Dark Mode

macOS dark mode is handled natively by AppKit:

• NSAppearanceNameDarkAqua — The backend sets the application appearance to NSAppearanceNameDarkAqua when the system is in dark mode. All standard Cocoa controls automatically adapt their colors.
• Automatic control colors — NSColor provides semantic colors (labelColor, controlColor, windowBackgroundColor) that automatically switch between light and dark variants.
• System theme observation — The backend registers for NSApplicationDidChangeScreenParametersNotification to detect theme changes at runtime.

// cocoa_backend.mm - Dark mode setup
void SetupAppearance(void)
{
   // Follow the system appearance (light or dark)
   [[NSApplication sharedApplication] setAppearance:nil];

   // To force dark mode regardless of system setting:
   // NSAppearance * dark = [NSAppearance appearanceNamed:NSAppearanceNameDarkAqua];
   // [[NSApplication sharedApplication] setAppearance:dark];
}

Scintilla Integration

On macOS, Scintilla 5.5.3 is built as a static library and linked directly into the HarbourBuilder binary:

The Scintilla view is embedded as an SCIView (Scintilla's Cocoa view class) within the code editor tab. It communicates via the Scintilla direct function interface.

// Embedding Scintilla in the Cocoa view hierarchy
@interface HBCodeEditorView : NSView
@property (strong) SCIView * scintillaView;
@end

// Create and configure
SCIView * sciView = [[SCIView alloc] initWithFrame:frame];
Scintilla_SendMessage( sciView, SCI_SETLEXER, SCLEX_CPP, 0 );
Scintilla_SendMessage( sciView, SCI_SETSTYLEBITS, 8, 0 );

Build Process

Prerequisites

1. Xcode Command Line Tools — This is the only prerequisite. Install with:

   xcode-select --install

   This provides clang, make, and the macOS SDK headers.
2. No separate Harbour install needed — The build script downloads and compiles Harbour automatically if it's not already present.

Build Script (build_mac.sh)

The script performs these steps:

1. Check for Harbour — If $HBDIR is not set or Harbour is not found at ~/harbour, it clones and compiles Harbour from github.com/harbour/core.
2. Build Scintilla — Downloads Scintilla 5.5.3 source and builds libscintilla.a and liblexilla.a as static libraries.
3. Compile the IDE — Compiles HarbourBuilder source using the Harbour compiler and clang for the Objective-C++ backend.
4. Link — Links against the macOS frameworks: -framework Cocoa, -framework Foundation, -framework AppKit, plus the Harbour runtime and Scintilla static libs.

# build_mac.sh - Typical build session
cd HarbourBuilder/samples
./build_mac.sh

# Copy to bin/ and run
cp HbBuilder ../bin/
../bin/HbBuilder

Apple Silicon Considerations

The default build targets x86_64 for compatibility. On Apple Silicon Macs (M1/M2/M3/M4), the binary runs under Rosetta 2 translation. For native ARM64 builds:

1. Recompile Harbour for darwin/clang/arm64
2. Update HBDIR in build_mac.sh to point to the ARM64 Harbour build
3. Rebuild Scintilla with -arch arm64
4. Build HarbourBuilder with clang -arch arm64

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

.app Bundle Creation

To distribute a HarbourBuilder application as a standard macOS application bundle:

MyApp.app/
├── Contents/
│   ├── Info.plist          // Bundle metadata
│   ├── MacOS/
│   │   └── MyApp           // The compiled binary
│   ├── Resources/
│   │   ├── icon.icns       // Application icon
│   │   └── MainMenu.nib    // (optional) MainMenu
│   └── PkgInfo             // APPL????

The Info.plist must include at minimum:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleExecutable</key>
    <string>MyApp</string>
    <key>CFBundleIconFile</key>
    <string>icon</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>NSHighResolutionCapable</key>
    <true/>
</dict>
</plist>

Platform-Specific Features

Known Limitations

• Gatekeeper — Unsigned applications may be blocked by Gatekeeper. Right-click → Open, or remove quarantine: xattr -d com.apple.quarantine HbBuilder.
• Notarization — For distribution to other Macs, the binary should be notarized through Apple's Developer ID program.
• Scintilla version — The macOS backend uses Scintilla 5.5.3 (vs 5.6.1 on Windows/Linux) due to Cocoa-specific compatibility requirements in the newer version.
• ARM64 — Native Apple Silicon builds require manual recompilation of Harbour and Scintilla for arm64.

Dependencies