# Annotation Type Mac

@Retention(CLASS) @Target(TYPE) public @interface Mac

Native macOS build hints, checked by the compiler.

Place this on your application's main class -- the class named by `codename1.mainName`. An attribute you do not set is not written at all, so the build server's own default applies. The `default` clause below each attribute names a constant that says nothing -- see `HintUnset` -- and this package deliberately does not record what the server would do instead, because that is the server's to change.

The platform is stated once on the annotation, not on every attribute. An attribute repeats it only to disagree with it.

These are the `macos.*` hints, which the native macOS build reads. Every one of them is also accepted spelled `macNative.*`, the name the legacy Mac Catalyst target uses, so a project moving between the two keeps building; the canonical spelling is the one here.

- ## Optional Element Summary

  Optional Elements
  Modifier and Type
  Optional Element
  Description
  `String[]`
  `addLibs`
  macOS builds.
  `String`
  `appCategory`
  macOS builds.
  `String`
  `arch`
  macOS builds.
  `String`
  `bundleId`
  macOS builds.
  `String`
  `bundleVersion`
  macOS builds.
  `String`
  `configuration`
  macOS builds.
  `String`
  `copyright`
  macOS builds.
  `Toggle`
  `cryptoGcm`
  macOS builds.
  `Toggle`
  `deriveBundleId`
  macOS builds.
  `String`
  `distribution`
  macOS builds.
  `Toggle`
  `entitlementsAllowJit`
  macOS builds.
  `Toggle`
  `entitlementsAppSandbox`
  macOS builds.
  `String`
  `entitlementsExtra`
  macOS builds.
  `Toggle`
  `entitlementsFilesDownloads`
  macOS builds.
  `FileAccess`
  `entitlementsFilesUserSelected`
  macOS builds.
  `Toggle`
  `entitlementsHardenedRuntime`
  macOS builds.
  `Toggle`
  `entitlementsNetworkClient`
  macOS builds.
  `Toggle`
  `entitlementsNetworkServer`
  macOS builds.
  `String`
  `fixedWindowSize`
  macOS builds.
  `Toggle`
  `hardenedRuntime`
  macOS builds.
  `Toggle`
  `loadsExternalCode`
  macOS builds.
  `String`
  `minDeploymentTarget`
  macOS builds.
  `String`
  `packaging`
  macOS builds.
  `String`
  `plistInject`
  macOS builds.
  `String`
  `provisioningProfileAppStore`
  macOS builds.
  `String`
  `provisioningProfileDeveloperID`
  macOS builds.
  `String`
  `signingIdentityAppStore`
  macOS builds.
  `String`
  `signingIdentityDeveloperID`
  macOS builds.
  `String`
  `signingIdentityInstaller`
  macOS builds.
  `String`
  `signingIdentityInstallerAppStore`
  macOS builds.
  `String`
  `signingIdentityInstallerDeveloperID`
  macOS builds.
  `String`
  `signingStyle`
  macOS builds.
  `Toggle`
  `sourceOnly`
  macOS builds.
  `String`
  `teamId`
  macOS builds.
  `String`
  `themeMode`
  macOS builds.
  `String`
  `urlSchemes`
  macOS builds.

- ## Element Details

  - ### addLibs

    String[] addLibs
    macOS builds. Frameworks to link in addition to the ones the build detects for itself, separated by a semicolon, a comma or a colon -- for example `Speech.framework;CoreMIDI.framework`. `ios.add_libs` is read when this is unset, so a project migrated from the Mac Catalyst build keeps linking what its native sources need.
    Default:
      `{}`

  - ### appCategory

    String appCategory
    macOS builds. `LSApplicationCategoryType` in the generated Info.plist. Default `public.app-category.utilities`. See https://developer.apple.com/documentation/bundleresources/information_property_list/lsapplicationcategorytype[Apple's category list].
    Default:
      `""`

  - ### arch

    String arch
    macOS builds. The architectures to compile, as an `ARCHS` value. Default `arm64 x86_64`, which is what a Mac application is expected to be: a single-architecture build is the kind of thing nobody notices until an Intel user reports it.
    Default:
      `"arm64 x86_64"`

  - ### bundleId

    String bundleId
    macOS builds. Used only when `macos.deriveBundleId=false`. Default: `<packageName>.mac`.
    Default:
      `""`

  - ### bundleVersion

    String bundleVersion
    macOS builds. `CFBundleVersion` in the Info.plist. `ios.bundleVersion` is read when this is unset, and the project's version when neither is set.
    Default:
      `""`

  - ### configuration

    String configuration
    macOS builds. The Xcode configuration to archive, as passed to `xcodebuild -configuration`. Default `Release`.
    Default:
      `"Release"`

  - ### copyright

    String copyright
    macOS builds. `NSHumanReadableCopyright` in the Info.plist. Defaults to `Copyright (c) <year> <vendor>`.
    Default:
      `""`

  - ### cryptoGcm

    Toggle cryptoGcm
    macOS builds. Whether AES-GCM is compiled into the bundled crypto library. On by default wherever the crypto API is on, matching what an iOS build of the same application gets; set `false` to leave it out and keep the symbol set smaller. `ios.crypto.gcm` is read when this is unset.
    Default:
      `DEFAULT`

  - ### deriveBundleId

    Toggle deriveBundleId
    macOS builds. `false` (default) gives the app its own bundle identifier, `<packageName>.mac`, because a macOS app and an iOS app are separate products in App Store Connect. `true` reuses the iOS identifier. On the legacy Mac Catalyst target this maps instead to Xcode's `DERIVE_MACCATALYST_PRODUCT_BUNDLE_IDENTIFIER`, which appends `.maccatalyst`.
    Default:
      `DEFAULT`

  - ### distribution

    String distribution
    macOS builds. Every `macos.*` hint below is also accepted spelled `macNative.*`, which is what the legacy Mac Catalyst target reads, so an existing Catalyst project keeps building unchanged. `developerID` (default), `appStore`, or `both`. Selects the signing certificate, the entitlements and the default packaging. `both` is genuinely two builds: the channels differ in the certificate and in the entitlements the signature carries -- the App Store one has to be sandboxed -- so one binary can't be relabelled into the other channel afterwards. It produces `<App>-appstore.app` and `<App>-developerid.app`, each with its own container.
    Default:
      `""`

  - ### entitlementsAllowJit

    Toggle entitlementsAllowJit
    macOS builds. `true` enables `com.apple.security.cs.allow-jit` for hardened runtime. ParparVM is AOT-compiled so this is `false` by default; flip when bundling a JIT-using cn1lib.
    Default:
      `DEFAULT`

  - ### entitlementsAppSandbox

    Toggle entitlementsAppSandbox
    macOS builds. `true` enables `com.apple.security.app-sandbox`. Default is `true` for the `appStore` channel, `false` for `developerID`. The App Store channel is always sandboxed whatever this says -- the Mac App Store requires it, and a package built without the sandbox gets rejected at submission rather than at build time. The refusal is reported in the build log.
    Default:
      `DEFAULT`

  - ### entitlementsExtra

    String entitlementsExtra
    macOS builds. Free-form XML inserted verbatim inside the `<dict>...</dict>` of the generated entitlements plist. Use for entitlements Codename One doesn't expose individually.
    Default:
      `""`

  - ### entitlementsFilesDownloads

    Toggle entitlementsFilesDownloads
    macOS builds. `true` adds `com.apple.security.files.downloads.read-write`, which is access to the Downloads folder without a panel. Default `false`, and separate from `macos.entitlements.files.userSelected` above because it's a wider grant than picking a file.
    Default:
      `DEFAULT`

  - ### entitlementsFilesUserSelected

    FileAccess entitlementsFilesUserSelected
    macOS builds. `readwrite` (default), `readonly`, or `none`. Sets the matching `com.apple.security.files.user-selected.*` entitlement -- the files the user picks in an open or save panel, and nothing else.
    Default:
      `DEFAULT`

  - ### entitlementsHardenedRuntime

    Toggle entitlementsHardenedRuntime
    macOS builds. `true` writes `com.apple.security.cs.allow-jit` and `com.apple.security.cs.allow-unsigned-executable-memory` into the entitlements as explicit denials; `false` leaves them out. It doesn't switch the hardened runtime on or off -- that's `macos.hardenedRuntime` above. Default is `true` for `developerID`, `false` for `appStore`.
    Default:
      `DEFAULT`

  - ### entitlementsNetworkClient

    Toggle entitlementsNetworkClient
    macOS builds. Toggles `com.apple.security.network.client`. Default `true`.
    Default:
      `DEFAULT`

  - ### entitlementsNetworkServer

    Toggle entitlementsNetworkServer
    macOS builds. Toggles `com.apple.security.network.server`. Default `false`.
    Default:
      `DEFAULT`

  - ### fixedWindowSize

    String fixedWindowSize
    macOS builds. Opt-in. Format `<width>x<height>` -- for example `1024x685`. When set, the window's minimum and maximum size are pinned to the requested size so every launch produces a byte-identical window. Default unset, in which case the window is resizable. The CI screenshot pipeline turns this on to keep the strict-pixel golden comparison stable; production apps should leave it off.
    Default:
      `""`

  - ### hardenedRuntime

    Toggle hardenedRuntime
    macOS builds. Sets Xcode's `ENABLE_HARDENED_RUNTIME`. Default `true`, because notarization requires it. This is the build setting; the entitlement hint below is a different thing despite the similar name.
    Default:
      `DEFAULT`

  - ### loadsExternalCode

    Toggle loadsExternalCode
    macOS builds. `true` grants the hardened-runtime exception for loading unsigned libraries. A Codename One application doesn't load code that way, but a cn1lib shipping a dylib needs this, or the load is refused at runtime with nothing in the application's own logs.
    Default:
      `DEFAULT`

  - ### minDeploymentTarget

    String minDeploymentTarget
    macOS builds. Minimum macOS version (`MACOSX_DEPLOYMENT_TARGET`). Default `11.0` on the native macOS build, which is the floor for a universal Apple silicon binary. The legacy Mac Catalyst target defaults to `10.15`.
    Default:
      `""`

  - ### packaging

    String packaging
    macOS builds. `app`, `dmg`, `pkg` or `both`. Unset, each channel takes its own default -- `pkg` for `appStore`, because productbuild's output is what you upload, and `dmg` for `developerID`. Set explicitly, the value applies to every channel. A cloud build always ships a file, so `app` there means the bundle zipped with `ditto` rather than the raw `.app` directory.
    Default:
      `""`

  - ### themeMode

    String themeMode
    macOS builds. Which native theme the application installs: `modern` (equivalently `liquid` or `material`) or `ios7` (equivalently `flat`). Defaults to `modern`, which is where this target parts company with iOS -- iOS keeps the legacy theme by default so that applications already shipped, and their screenshot baselines, keep rendering as before. There is no such history here, and the legacy theme defines no dark styles at all, so an application on it renders light however it asks for dark. The cross-platform `nativeTheme` hint is honoured when this is unset, with `legacy` mapping to `ios7`.
    Default:
      `""`

  - ### plistInject

    String plistInject
    macOS builds. Raw XML members added to the generated `Info.plist`, the same form `ios.plistInject` takes -- for example `<key>NSAppTransportSecurity</key><dict/>`. A key that the build also generates is replaced by the injected one, and the build log names it. `ios.plistInject` is read when this is unset, so a project migrated from the Mac Catalyst build keeps its injections.
    Default:
      `""`

  - ### provisioningProfileAppStore

    String provisioningProfileAppStore
    macOS builds. Provisioning profile name for App Store distribution -- used only when `macNative.signing.style=manual`.
    Default:
      `""`

  - ### provisioningProfileDeveloperID

    String provisioningProfileDeveloperID
    macOS builds. Provisioning profile name for Developer ID distribution -- used only when `macNative.signing.style=manual`.
    Default:
      `""`

  - ### signingStyle

    String signingStyle
    macOS builds. `manual` (default) signs with the certificate identity hints below, verbatim. `automatic` lets Xcode resolve the certificate from the team and provisioning profile instead. Manual is the default because a build server has an installed certificate and no Xcode account session, and automatic signing there stops to ask you to sign in; use automatic when building on your own machine.
    Default:
      `""`

  - ### signingIdentityAppStore

    String signingIdentityAppStore

    macOS builds. Signing certificate identity for the App Store channel. Default `Apple Distribution`.

    Unlike the Developer ID channel, this one rejects `none`. An unsigned application still gets packaged into a signed `.pkg`, so the build reports success and App Store Connect rejects the upload hours later for an application with no signature and none of the sandbox entitlements it has to carry. The build fails immediately instead, naming this hint. Build only the `developerID` channel to get an unsigned application.

    An empty value reads as unset and takes the default, which is why the Developer ID channel spells the escape hatch `none` rather than "".

    Default:
      `""`

  - ### signingIdentityDeveloperID

    String signingIdentityDeveloperID
    macOS builds. Signing certificate identity for the Developer ID channel. Default `Developer ID Application`. Set it to `none` to build unsigned.
    Default:
      `""`

  - ### signingIdentityInstaller

    String signingIdentityInstaller
    macOS builds. The certificate `productbuild` signs a `.pkg` with -- `3rd Party Mac Developer Installer` for the App Store, `Developer ID Installer` for direct distribution. This is a different certificate from `macos.signingIdentity.appStore`, which signs the application, so it has a hint of its own rather than being derived from that one. Required whenever a package is produced, which includes the App Store default: the build fails with an explanatory error rather than writing an unsigned package, because App Store Connect refuses one and Gatekeeper won't accept it as Developer ID distribution however well the enclosed application is signed.
    Default:
      `""`

  - ### signingIdentityInstallerAppStore

    String signingIdentityInstallerAppStore
    macOS builds. The installer certificate for the App Store channel specifically, when `macos.distribution=both` produces a package on each side. They're different certificates, so one shared value signs both packages with the same one and leaves one of them unusable. Unset, the shared `macos.signingIdentity.installer` applies.
    Default:
      `""`

  - ### signingIdentityInstallerDeveloperID

    String signingIdentityInstallerDeveloperID
    macOS builds. The installer certificate for the Developer ID channel specifically. Unset, the shared `macos.signingIdentity.installer` applies.
    Default:
      `""`

  - ### sourceOnly

    Toggle sourceOnly
    macOS builds. `true` stops after generating the Xcode project, which is what the `mac-source` target delivers. Set by that target rather than by hand.
    Default:
      `DEFAULT`

  - ### teamId

    String teamId
    macOS builds. Apple Developer Team ID (alphanumeric). Falls back to `ios.release.teamId` -> `ios.teamId` -> `ios.debug.teamId` since most apps share a single Apple Developer Team for iOS and Mac.
    Default:
      `""`

  - ### urlSchemes

    String urlSchemes
    macOS builds. Custom URL schemes to register, comma separated. `ios.urlSchemes` and then `ios.urlScheme` are read when this is unset, so a project migrated from the Mac Catalyst build keeps its deep links.
    Default:
      `""`