iOS Platform Guide iOS

HarbourBuilder can build native iOS applications using UIKit controls, following the same UI_* API used for Android. Your Harbour PRG code compiles to native arm64 machine code — no web views, no interpreters.

Architecture

The iOS backend uses the same event-loop-inversion pattern as Android:

iOS owns the event loop — UIApplicationMain() runs the Cocoa Touch event loop, not Harbour.
Harbour VM starts inside AppDelegate — application:didFinishLaunchingWithOptions: calls hb_vmInit() which runs your Main().
UI_* functions create UIKit controls — UILabel, UIButton, UITextField are created directly in Objective-C.
Click events dispatch to Harbour codeblocks — UIButton target/action calls hb_evalBlock0().

Prerequisites

macOS with Xcode 15+ installed
iOS SDK (installed via Xcode > Settings > Platforms)
Harbour for macOS (host compiler for PRG→C translation)
Harbour for iOS cross-compiled libraries

Setup

Run the setup wizard from the IDE menu: Run > iOS Setup Wizard

Or manually from the terminal:

cd source/backends/ios
./setup-ios-toolchain.sh

This will:

Verify Xcode and iOS SDK are installed
Download the iOS Simulator runtime if missing
Build Harbour for iOS (arm64 device + x86_64 simulator) via bootstrap-harbour.sh

Building

From the IDE: Run > Run on iOS

Or manually:

# Build for simulator
./build-ios-app.sh hello_ios.prg simulator

# Build for device
./build-ios-app.sh hello_ios.prg device

The build pipeline has 4 stages:

PRG → C: Harbour compiler translates your .prg to C
Cross-compile: Clang compiles C + ios_core.m for iOS
Link: Link with Harbour iOS libraries + UIKit frameworks
Bundle: Create .app with Info.plist and codesign

Running on Simulator

./install-and-run.sh

Or manually:

xcrun simctl boot "iPhone 16"
xcrun simctl install booted /tmp/HarbouriOS/app-build/HarbourApp.app
xcrun simctl launch booted com.harbour.builder.app

UI_* API Reference

Function	Description
`UI_FormNew(cTitle, nW, nH)`	Create UIViewController with root UIView
`UI_FormShow(hForm)`	No-op (form is visible on creation)
`UI_FormRun(hForm)`	No-op (iOS owns the event loop)
`UI_LabelNew(hParent, cText, nX, nY, nW, nH)`	Create UILabel
`UI_ButtonNew(hParent, cText, nX, nY, nW, nH)`	Create UIButton (system type)
`UI_EditNew(hParent, cText, nX, nY, nW, nH)`	Create UITextField
`UI_SetText(hCtrl, cText)`	Set control text
`UI_GetText(hCtrl)`	Get control text
`UI_OnClick(hCtrl, bBlock)`	Register click handler codeblock
`UI_SetFormColor(nClr)`	Set form background (BGR COLORREF)
`UI_SetCtrlColor(hCtrl, nClr)`	Set control background (BGR COLORREF)
`UI_SetCtrlFont(hCtrl, cFamily, nSize)`	Set font family and size (points)

Color Format

Colors use the Win32 COLORREF format: 0x00BBGGRR (BGR). This is the same format used by Android and Win32 backends, so your PRG code is portable across platforms.

Harbour iOS Patches

Three small patches were needed to build Harbour for iOS:

src/rtl/hbrunfun.c — system() is unavailable on iOS, returns -1
src/rtl/run.c — same system() guard
src/common/hbfopen.c — same system() guard
include/hbdefs.h — auto-detect iOS via TargetConditionals.h

These patches are applied automatically by bootstrap-harbour.sh.

File Structure

source/backends/ios/
  ios_core.m              # UIKit backend (HB_FUNCs + AppDelegate + main)
  hello_ios.prg           # Demo app
  bootstrap-harbour.sh    # Cross-compile Harbour for iOS
  build-ios-app.sh        # Build .app from PRG
  install-and-run.sh      # Install and launch on simulator
  setup-ios-toolchain.sh  # Verify/install toolchain

Getting Started

Platforms