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.

  • 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:
      ""