Debugging Mac Applications

Yo can debug your macOS and Mac Catalyst projects on your Mac, directly from Fire or remotely from Water or [Visual Studio](/Visual Studio).

macOS Projects

macOS projects are projects ste to build directly for macOS and it's APIs, including low-level frameworks such as Foundation, and higher-level UI frameworks such as AppKit. macOS projects can run and debug only on the Mac.

In Fire, "Mac" will automatically be selected as the default run destination in the CrossBox device picker. In Water or [Visual Studio](/Visual Studio), you must select (or newly connect to) a remote Mac, first.

Once done, simply select "Run" ("Start" in Visual Studio), or press ⌘R (Fire) or Ctrl+R (Water) or F5 (Visual Studio) to run your app. When developing on Windows, your app[ will first be transfered to or updated on the remote Mac (parts may already be there from the build), before it launches.


By default Mac apps build for the architecture of your local Mac – arm64 for newer Apple Silicon-based Macs, and x86_64 for older Intel-based Macs, so that they will run natively.

On Apple Silicon-based Macs, you can optionally also debug the x86_64 version of your project in the Rosetta 2 translation layer. This can be useful of your application contains architecture-specific code or behaviors that need to be tested separately, or to debug problems specific to the Intel build of your app.

With a Mac project open, you will find that in addition to the local "Mac" entry in ther CrossBox device picker, you will also see a second entry named "Mac (Rosetta)". Selecting this item as the target device will force your application to run it's x86_64 slice in the translation layer.

Note that you will need to manually change your project to include the x64_64 architecture in Project Settings for tis to work. Also note that if you set a project to build only for x86_64, it will always run under Rosetta.

No translation for arm64 binaries is available on Intel-based Macs, so you will omly be able to run and debug x86_64 binaries on those machines (although you can of course build from arm64, for deployment.

Mac Catalyst Applications

Mac Catalyst apps are projects that target iOS and use the UIKit based GUI frameworks, but are set to optionally also run as native(-ish) Mac applications (not to be confused with iOS apps themselves that can be run on Apple Silicon-based Macs).

Mac Catalyst can be enabled in your iOS project by setting the "SupportMacCatalyst" Project Settings to True. Once done, "Mac" becomes available as an option in the CrossBox debice picker, next to your real devices and Simulators. Selecting this option and running will build your app for the "Mac" Build Destination and run it locally on your Mac.

Note that the Mac Catalyst build of your app is not the same as your regular iOSM (or Simulator) built, even thou it uses a very similar set of frameworks, and might be targeting the same architecture(a). Mac Catalyst apps have access to additional APIs to make apps more "Mac-like", and you can check for Mac Catalyst vs iOS speciifc code both at compile-time (e.g. if  defined("MACCATALYST")) and runtime (e.g. checking UIDevice.current.userInterfaceIdiom for Mac).

iOS Applications on Apple Silicon

While Apple Silicon-based Macs allow installing and running iOS (non-Mac Catalyst) apps from the App Store, it is currently not supported to run and debug apps in this mode. To test your iOS apps, you must either use a Device or Simulator, or a dedicated Mac Catalyst build as mentioned above.

Debug Engines

Elements ships with two debug engines for Cocoa project: the legacy LLDB debug engine and the new Island debug engine.

The legacy LLDB debug engine uses Apples standrad LLDB debugger internally. it is supported for Toffee projects and on Intel-based Macs only. It is the default debug engine on older macOS versions before Big Sur.

The new Island debug engine was developed fully in house, and provides support for both Objective-C ("Cocoa") and Island0native object models (as well as, in the future, Swift ABI). It is the default engine on Big Sur and later, and the only debug engine available when working on an Apple Silicon-based Mac.

Where applicable, you can toggle between the two engines in Project Settings via the Debug Engine setting.

See Also