Mac OS X Application Development

From RAD Studio
Jump to: navigation, search

Go Up to Cross-Platform Applications Index

You can use RAD Studio to create Mac OS X applications, and you can use your Mac as the required intermediate platform for iOS apps.

From the hardware point of view, in addition to the development PC, you need a Mac connected with the development computer (where RAD Studio is installed); for example, using a local area network (LAN). See FireMonkey Platform Prerequisites for a list of system requirements, both for your development PC and for the Mac. See also Working with a Mac and a PC.

The Delphi compiler for Mac OS X is DCCOSX.EXE.

The C++ compiler for Mac OS X is BCCOSX.EXE. The C++ linker for Mac OS X is XLINK.EXE.

Setting Up Your Cross-Platform Development Environment for Mac OS X

  • Physical Connection: Ensure that RAD Studio can connect with the target Mac:
    However, if the OS X app does not have an assigned connection profile, and you attempt to perform an operation that requires a connection profile, the IDE displays the following message:
    A connection profile is required for this operation but has not been assigned.
    Would you like to assign or create a profile now?
    Then the IDE guides you through the necessary steps in creating a connection profile. On the Platform Properties dialog, you can assign an existing profile to the target platform, or select Add New to create a new connection profile to assign to the target platform instead.
  • Platform Assistant: On the Mac, install the Platform Assistant and run it.
  • Target Platform: In the IDE, set the target platform. When you create a Delphi or C++Builder desktop application, RAD Studio sets Win32 as the default target platform.
    To change the target platform to OS X:
    1. Right-click the Target Platforms node in the Project Manager.
    2. Click Add Platform and select OS X.
    The OS X option is unavailable if the application uses VCL (VCL does not support OS X).
  • Connection Profile: In the IDE, create and assign a connection profile (a group of settings that characterize the connection to your target machine; see Creating and Testing a Connection Profile on the Development PC).
  • For C++ Development:
    • Xcode and Xcode Command Line Tools:
      For C++ OS X applications, you need to install Xcode on the Mac. You need to install the Xcode Command Line Tools as well in order to deploy applications to the Mac App Store.
    • SDK:
      For C++, add an SDK, which consists of a set of files (headers and libraries) that are pulled from the machine running the Platform Assistant server into your development system, for compiling and linking. See Adding a Mac OS X or iOS Device SDK.

Acquiring the Required Apple IDs

Developing, Testing, and Self-Distribution of OS X Apps: Apple does not require you to either register or join the Apple Developer Program. Although you need to obtain an Apple ID in order to download the Xcode IDE from the App Store, neither Xcode nor your computer need any form of registration. However, you need to join the Mac Developer Program if you want to distribute your apps via the Mac App Store. (Similarly, you need to join the iOS Developer Program if you want to distribute your apps via the iOS App Store.) Joining the Mac Developer Program entitles you to access a wealth of developer resources that are otherwise unavailable.

You might need several IDs, available from and subject to change by Apple Computers, as follows:

Apple ID and iTunes ID

In order to buy either apps (from the Mac App Store) or music (from the iTunes Store), you need to acquire an Apple ID (free) and an iTunes account (free):

Apple Developer ID

In order to distribute your Mac apps in the Mac App Store, you need to:

  • Acquire an Apple Developer ID (free)
  • Join a Mac Developer Program ($99/year for an individual developer)
    The Mac Developer Program provides you with the tools you need on the Mac (such as Xcode and the SDK), online documentation, and support. Separate Mac developer programs are available for individuals, companies, and universities, and registration for the group programs costs less per person than for an individual developer.
  • Obtain signing certificates from (Mac App Developer Certificate Utility).
    You might need the following types of signing certificates (hypothetical certificate names are given):
    • Development Certificate:
      • Mac App Development Certificate
    • Distribution Certificates:
      • Mac App Store Certificates:
        • Mac App Certificate
        • Mac Installer Certificate
      • Developer ID Certificates:
        • Developer ID Application Certificate
        • Developer ID Installer Certificate

You need to provide your two Distribution certificate names in the Provisioning page when you do a product build for submission to the Mac App Store.

Sandboxing Is Required for Submitting Apps to the Mac App Store

Sandboxing restricts an application's access to system resources and is one way that Apple ensures that apps are safe and do not contain any malware.

Using the IDE to Sandbox, Code Sign, and Prepare Your App (Recommended Method)

If you want to submit your application to the Mac App Store, you need to comply with Apple sandboxing requirements. The recommended method is to use the IDE as described here. The manual steps are presented for introduction only; you will find the most up-to-date information on the Apple Web pages.

The RAD Studio IDE can handle sandboxing entitlements for you, and can perform the necessary code-signing and product build using your 3rd Party Mac Developer Application certificate and your 3rd Party Mac Developer Installer certificate, respectively.

You will need to complete the following pages in the IDE:

  • Entitlement List - For specifying access entitlements for your application.
  • Provisioning - For code signing and product build, prior to submitting your application to the Mac App Store.

1. Obtaining Certificates and Entering Them in the IDE

Specific certificates are required for submitting apps to the Mac App Store:

  1. Using Xcode on the Mac or using the Mac App Developer Certificate Utility (, obtain the following certificates:
    • A Mac App distribution certificate
    • A Mac Installer certificate
    You will need an Apple Developer Account to do this (see Acquiring the Required Apple IDs).
  2. Ensure that your Mac App distribution certificate is installed in your Mac Keychain (in the Finder, double-click the downloaded .cer file).
  3. On the Entitlement List page, assign the entitlements (system access rights) that you want for your application. An entitlements file is automatically created for you, and you can edit the entitlements list for your application using the Entitlement List page in Project Options.
  4. On the Provisioning page, enter your Mac App distribution and Mac Installer certificates.

2. Code Signing, Building, and Deploying your Mac OS X Application

Note: Before code-signing and building your application, you need to perform the normal build setup steps in RAD Studio:

  1. Set OS X as the target platform, assign a connection profile and an SDK (the latter for C++ only), and test the connection. (See Activating and Configuring the Target Platform.)
  2. Set Version Info.

When you are ready to prepare the final product build, just before submitting your application to the Mac App Store, do the following:

  1. In the Project Manager, activate the Application Store node within the Configuration node of the OS X target platform tree:
    This sets up your RAD Studio build to deliver a .pkg to the target Mac.
  2. Build your project in the IDE.
  3. Deploy your project using either of the following:
    • Project > Deployment - Click the Deploy command in the Deployment Manager
    • Run > Run (F9)
      For the Mac App Store target platform, deploying your application copies the project from the PC to the Mac, code-signs the application using your specified certificates, and produces a product build consisting of a .pkg located in the same directory with the .app file on the Mac.
    At this point, your application is code signed and ready to be submitted from your Mac to the Mac App Store.
  4. On the Mac, upload the app bundle using the Application Loader and iTunes Connect.

Using Manual Steps to Sandbox, Code Sign, and Build Your Application

Note: Using the IDE (as described above) is the recommended way to sandbox, code sign, and build your application (for submission to the Mac App Store). Manual steps are much more complex than using the IDE, and are only outlined here for those who need to work outside the IDE. You will find the most up-to-date information on the Apple Web pages.

If you are not using the IDE to prepare your app for the Mac App Store, you can do the necessary steps on your Mac. This section presents a basic introduction to this process, but for details you should rely on the Apple documentation (some links are provided here).

On the Mac, you need to create a ProjectName.entitlements file and place it in the application bundle, code-sign the bundle, package the bundle, and submit it to Apple.

Requirements from Apple

Here are the elements you need, and the relevant information from Apple:

Manually Code Signing and Building Your OS X Application on the Mac

Code signing and provisioning are required if you want to submit your application to the Mac App Store. You can perform these steps either using the IDE (as described earlier in this topic), or manually (by following the general directions given below).


  • Ensure that you obtain a distribution certificate for submitting apps to the Mac App Store from
  • You will need an Apple Developer Account to do this (see Acquiring the Required Apple IDs).
  • Ensure that the certificate is installed in your Keychain (double-click the .cer file in the Finder).
  • You will need an .entitlements file (XML) for Mac sandboxing (this file is created for you in the Entitlement List page if you use the IDE).

To manually code sign and build a product installer for your Mac OS X application:

  1. Build your application in the IDE and deploy it to Mac OS X (Lion or Mountain Lion).
  2. Open a terminal window on the Mac.
  3. Switch to the paserver's scratch-dir, for example:
  4. Run the following commands:
  • Code-sign your application:
sudo codesign -f -v -s "Mac Developer: FirstName LastName" ""
  • Do a productbuild, creating an installer package:
sudo productbuild --component "" /Applications --sign "Mac Developer: FirstName LastName" --product "" AppName.pkg
Useful Apple URL

Submitting Your Application to the Mac App Store

You can distribute Mac applications outside of the Mac App Store, but if you want to sell your application in the Mac App Store, there are a few extra steps to perform.

  1. Make sure you have an iTunes Connect account. For more information, see the iTunes Connect Developer's Guide, such as: Overview of iTunes Connect
  2. Create a 512x512 application icon (.ico file) and add it to your project.
  3. Build and debug your Mac OS X application in RAD Studio.
  4. Acquire the necessary Apple developer certificates (described in Acquiring the Required Apple IDs).
  5. Complete the Entitlement List in Project > Options and the Provisioning page in either Project > Options or Tools > Options.
  6. Do a final build, and deploy to the Mac using the Deployment Manager.
  7. Using either Xcode or the Mac Application Loader, submit your application archive (.pkg) to the Mac App Store (see URL below).
  8. Manage your app in the App Store by using iTunes Connect.

Useful Apple URLs

Using Frameworks in Mac Apps

Delphi RTL

Some RTL units that provide basic functionality are common for Mac and Windows, such as System.pas or System.SysUtils.pas.

A number of RTL units are Mac-only (see Mac Objective-C Frameworks). These units are prefixed with the Macapi or Posix unit scope.


The FireMonkey framework is ideal for the Mac OS X target platform, and it also supports both Win32 and Win64. See FireMonkey Platform Prerequisites.

VCL (not available for Mac)

The VCL is available only on Windows (32-bit or 64-bit).

Mac C RTL (for C/C++ Development)

BCCOSX.EXE uses header files from several locations for compilation.

The C RTL is distributed in two locations:

Include Path Type





This directory contains C/C++ RTL header files (.h) provided by RAD Studio. Some of these files include C/C++ header files from $(SYSROOT)\usr\include. For more information see OS X C RTL.



This directory contains C/C++ RTL Mac OS X header files cached on Windows. It is the SDK root directory.

For compilation, RAD Studio requires header files that reside on the Mac in the /usr/include directory. If you do not have such a directory on your Mac, then you must install Xcode. With the help of PAServer.exe, the Platform Assistant server, RAD Studio automatically copies the header files from Mac to Windows (from /usr/include to $(SYSROOT)\usr\include) when you add an SDK from the SDK Manager page.

Most of the Mac OS X C RTL is standard, and nonstandard characters are not supported.

Mac C Frameworks (for C/C++ Development)

Mac OS X frameworks provide various useful functions for writing platform-specific software. Some frameworks are C-based and can be included in a RAD Studio C++Builder project. Some frameworks are Objective-C-based (such as Foundation) and can be used only through Delphi interfaces (see the following section).

In order to include a Mac C framework in a RAD Studio project, you must edit the SDK that you use. Open the SDK Manager page and click the AddNewPathItem.bmp (Add a new path item) button from the right hand side. In the Add Remote Path Item or Edit Remote Path Item dialog, specify the following:

  • Framework remote path (example: /System/Library/Frameworks)
  • Framework name (example: CoreFoundation)

Back to the SDK Manager page, press Update Local File Cache to update the SDK local files.

For more information about using frameworks with BCCOSX, see --framework and OpenGL Multicolor Tetrahedron (C++).

Mac Objective-C Frameworks (Macapi)

The RTL contains a number of units that provide Delphi interfaces to Mac frameworks written in Objective-C. These units are scoped with Macapi (from Mac API) and typically located in the /source directory of your product installation:

  • Macapi.AppKit
  • Macapi.CocoaTypes
  • Macapi.Consts
  • Macapi.CoreFoundation
  • Macapi.CoreGraphics
  • Macapi.CoreServices
  • Macapi.CoreText
  • Macapi.Foundation
  • Macapi.ImageIO
  • Macapi.Mach
  • Macapi.ObjCRuntime
  • Macapi.ObjectiveC
  • Macapi.OCMarshal
  • Macapi.OpenGL
  • Macapi.QuartzCore
  • Macapi.Security
  • Macapi.SystemConfiguration

The FireMonkey framework relies on some of these units.

For help on these API, see the Apple documentation at Mac Developer Library.

Exception Handling

System.SysUtils contains a number of exception classes that represent non-language/hardware exceptions. These exception classes derive from EExternal. The following exception categories are covered:

  • Floating-point exceptions
  • Integer divide exceptions
  • Privileged instruction violations
  • Memory access violations

On the Mac, most of the EExternal exceptions originate as Mach exceptions. The only ones that do not originate as Mach exceptions are CTRL+C (EControlC) and CTRL+BREAK (EQuit).

If you use assembly routines, then see PC-Mapped Exceptions, Unwinding Assembly Routines.

Processing of Mach Exceptions

For Mach exceptions, the RTL from System.SysUtils creates a thread that listens for exception notifications from the operating system. You just have to include in your code the System.SysUtils unit. When the listening thread receives a Mach exception notification, it transforms the Mach exception into the corresponding Pascal language exception derived from EExternal, as appropriate, and raises/throws the Pascal exception to the user thread that caused the original Mach exception.

If you want to directly work with Mach exceptions, then be aware that, by including System.SysUtils, a dedicated thread is started for listening Mach exceptions. You can investigate the System.Internal.MachExceptions.pas source to make sure you do not interfere with the RTL.


For CTRL+C and CTRL+BREAK, the application installs signal handlers. (OS X does not create Mach exceptions for CTRL+C and CTRL+BREAK.)

The SIGINT and SIGQUIT handlers are in conformity with the standards that define the way shell applications must treat CTRL+C and CTRL+BREAK.

We strongly recommend that you do not override the SIGINT and SIGQUIT handlers. However, if you do this, you do not receive EControlC and EQuit exceptions.

Icons for Your OS X Apps

Your Mac app will need an application icon. To assign an icon set file (.icns file) to your application, select Project > Options > Application.

RAD Studio provides personality-specific .icns files for your Mac applications; the .ico and .icns files are available in the $(BDS)\bin and $(BDS)\bin64 directories. Each .icns file contains a set of icons of various sizes, which are internally selected on the Mac for different versions or form factors of the application:

  • delphi_PROJECTICNS.icns DelphiPROJICON.png
  • cbuilder_PROJECTICNS.icns CbuilderPROJICON.png

When you create an OS X application, the IDE creates an .icns file from the .ico file. The IDE automatically selects an icon from the .ico file, converts the icon to the .icns format (using the internal ico2icns utility), and includes the 512x512 icon in your Mac app bundle.

Icon Sizes for Retina and non-Retina Displays

To submit your app to the Mac App Store, the icon set file must include an icon with a resolution of 512x512 pixels, for non-Retina displays. You might want to add an icon with a resolution of 1024x1024 pixels, for Retina displays.

  • On the Mac, you can use Icon Composer to create Retina style (1024x1024) icons.
  • For more information about 1024x1024 icons, see Stackoverflow.

Documentation for Mac Libraries

You can obtain the Mac OS X documentation at the Mac OS X Developer Library. RAD Studio does not provide help for the libraries you might need to use on the Mac.

You can also register as a Mac developer (free of charge) at the Mac Dev Center. Being a registered member of the Mac Developer Program enables you to distribute apps in the App Store (this is along with other requirements, such as a developer certificate and a provisioning profile). For more information, see

Mac OS X Topics

See Also

Code Examples