Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# macOS Xcode project

Host Platform Support (Platform support)
macOS | Windows | Linux
--- | --- | ---
x86‑64 | arm64 | x86 | x86‑64 | arm64 | x86 | x86‑64 | arm | arm64
● | ● |  |  |  |  |  |  |

Briefcase supports creating a full Xcode project for a macOS app. This project can then be used to build an actual app bundle, with the `briefcase build` command or directly from Xcode.

By default, apps will be both signed and notarized when they are packaged.

## Packaging format

Briefcase supports three packaging formats for a macOS Xcode project:

1. A DMG that contains the `.app` bundle (using `briefcase package macOS Xcode -p dmg`).

2. A zipped `.app` folder (using `briefcase package macOS Xcode -p zip`).

3. A `.pkg` installer (using `briefcase package macOS Xcode -p pkg`).

`.pkg` is the required format for console apps. `.dmg` is the default format for GUI apps.

## Icon format

macOS Xcode projects use `.png` format icons. An application must provide icons of the following sizes:

- 16px

- 32px

- 64px

- 128px

- 256px

- 512px

- 1024px

macOS Xcode projects do not support splash screens.

## Additional options

The following options can be provided at the command line when packaging macOS apps.

### `--installer-identity <identity>`

This option is only used when creating a `.pkg` installer.

The code signing identity to use when signing the installer package. This is a different signing identity to the one used to sign the app, but it must be from the same team as the app signing identity.

### `--no-sign-installer`

This option is only used when creating a `.pkg` installer.

Do not sign the installer. This option can be useful during development and testing. However, care should be taken using this option for release artefacts, as it may not be possible to distribute an unsigned installer to others.

### `--no-notarize`

Do not submit the application for notarization. By default, apps will be submitted for notarization unless they have been signed with an ad-hoc signing identity.

### `--resume <submission ID>`

Apple’s notarization server can take a long time to respond - in some cases, hours. When you submit an app for notarization, the console output of the `package` command will provide you with a submission ID. If the notarization process is interrupted for any reason (including user intervention), you can use this submission ID with the `--resume` option to resume the notarization process for an app.

## Application configuration

The following options can be added to the `tool.briefcase.app.<appname>.macOS.Xcode` section of your `pyproject.toml` file.

### `entitlement`

A property whose sub-attributes define keys that will be added to the app’s `Entitlements.plist` file. Each entry will be converted into a key in the entitlements file. For example, specifying:

    entitlement."com.apple.vm.networking" = true

will result in an `Entitlements.plist` declaration of:

    <key>com.apple.vm.networking</key><true/>

Any Boolean or string value can be used for an entitlement value.

All macOS apps are automatically granted the following entitlements:

- `com.apple.security.cs.allow-unsigned-executable-memory`

- `com.apple.security.cs.disable-library-validation`

You can disable these default entitlements by defining them manually. For example, to enable library validation, you could add the following to your `pyproject.toml`:

    entitlement."com.apple.security.cs.disable-library-validation" = false

### `info`

A property whose sub-attributes define keys that will be added to the app’s `Info.plist` file. Each entry will be converted into a key in the entitlements file. For example, specifying:

    info."NSAppleScriptEnabled" = true

will result in an `Info.plist` declaration of:

    <key>NSAppleScriptEnabled</key><true/>

Any Boolean or string value can be used for an `Info.plist` value.

### `universal_build`

A Boolean, indicating whether Briefcase should build a universal app (i.e, an app that can target both x86_64 and ARM64). Defaults to `true`; if `false`, the binary will only be executable on the host platform on which it was built - i.e., if you build on an x86_64 machine, you will produce an x86_65 binary; if you build on an ARM64 machine, you will produce an ARM64 binary.

## Permissions

Briefcase cross platform permissions map to a combination of `info` and `entitlement` keys:

- `microphone`: an `info` entry for `NSMicrophoneUsageDescription`; and an `entitlement` of `com.apple.security.device.audio-input`

- `camera`: an `info` entry for `NSCameraUsageDescription`; and an `entitlement` of `com.apple.security.device.camera`

- `coarse_location`: an `info` entry for `NSLocationUsageDescription` (ignored if `background_location` or `fine_location` is defined); plus an entitlement of `com.apple.security.personal-information.location`

- `fine_location`: an `info` entry for `NSLocationUsageDescription``(ignored if ``background_location` is defined); plus an `entitlement` of `com.apple.security.personal-information.location`

- `background_location`: an `info` entry for `NSLocationUsageDescription`; plus an `entitlement` of `com.apple.security.personal-information.location`

- `photo_library`: an `info` entry for `NSPhotoLibraryUsageDescription`; plus an `entitlement` of `com.apple.security.personal-information.photos-library`

## Platform quirks

### Packaging with `--adhoc-sign`

Using the `--adhoc-sign` option on macOS produces an app that will be able to run on your own machine, but won’t run on any other computer. In order to distribute your app to other users, you will need to sign the app with a full signing identity.