@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.
Methods
Method details
addLibs
public abstract String[] addLibs() default {}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.appCategory
public abstract String appCategory() default ""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].arch
public abstract String arch() default "arm64 x86_64"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.bundleId
public abstract String bundleId() default ""macOS builds. Used only when
macos.deriveBundleId=false. Default:
<packageName>.mac.bundleVersion
public abstract String bundleVersion() default ""macOS builds.
CFBundleVersion in the Info.plist. ios.bundleVersion is
read when this is unset, and the project’s version when neither is set.configuration
public abstract String configuration() default "Release"macOS builds. The Xcode configuration to archive, as passed to
xcodebuild -configuration. Default Release.copyright
public abstract String copyright() default ""macOS builds.
NSHumanReadableCopyright in the Info.plist. Defaults to
Copyright (c) <year> <vendor>.cryptoGcm
public abstract Toggle cryptoGcm() default Toggle.DEFAULTmacOS 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.deriveBundleId
public abstract Toggle deriveBundleId() default Toggle.DEFAULTmacOS 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.distribution
public abstract String distribution() default ""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.entitlementsAllowJit
public abstract Toggle entitlementsAllowJit() default Toggle.DEFAULTmacOS 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.entitlementsAppSandbox
public abstract Toggle entitlementsAppSandbox() default Toggle.DEFAULTmacOS 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.entitlementsExtra
public abstract String entitlementsExtra() default ""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.entitlementsFilesDownloads
public abstract Toggle entitlementsFilesDownloads() default Toggle.DEFAULTmacOS 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.entitlementsFilesUserSelected
public abstract FileAccess entitlementsFilesUserSelected() default FileAccess.DEFAULTmacOS 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.entitlementsHardenedRuntime
public abstract Toggle entitlementsHardenedRuntime() default Toggle.DEFAULTmacOS 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.entitlementsNetworkClient
public abstract Toggle entitlementsNetworkClient() default Toggle.DEFAULTmacOS builds. Toggles
com.apple.security.network.client. Default true.entitlementsNetworkServer
public abstract Toggle entitlementsNetworkServer() default Toggle.DEFAULTmacOS builds. Toggles
com.apple.security.network.server. Default
false.fixedWindowSize
public abstract String fixedWindowSize() default ""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.hardenedRuntime
public abstract Toggle hardenedRuntime() default Toggle.DEFAULTmacOS 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.loadsExternalCode
public abstract Toggle loadsExternalCode() default Toggle.DEFAULTmacOS 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.minDeploymentTarget
public abstract String minDeploymentTarget() default ""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.packaging
public abstract String packaging() default ""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.themeMode
public abstract String themeMode() default ""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.plistInject
public abstract String plistInject() default ""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.provisioningProfileAppStore
public abstract String provisioningProfileAppStore() default ""macOS builds. Provisioning profile name for App Store distribution – used
only when
macNative.signing.style=manual.provisioningProfileDeveloperID
public abstract String provisioningProfileDeveloperID() default ""macOS builds. Provisioning profile name for Developer ID distribution –
used only when
macNative.signing.style=manual.signingStyle
public abstract String signingStyle() default ""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.signingIdentityAppStore
public abstract String signingIdentityAppStore() default ""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 “”.
signingIdentityDeveloperID
public abstract String signingIdentityDeveloperID() default ""macOS builds. Signing certificate identity for the Developer ID channel.
Default
Developer ID Application. Set it to none to build unsigned.signingIdentityInstaller
public abstract String signingIdentityInstaller() default ""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.signingIdentityInstallerAppStore
public abstract String signingIdentityInstallerAppStore() default ""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.signingIdentityInstallerDeveloperID
public abstract String signingIdentityInstallerDeveloperID() default ""macOS builds. The installer certificate for the Developer ID channel
specifically. Unset, the shared
macos.signingIdentity.installer applies.sourceOnly
public abstract Toggle sourceOnly() default Toggle.DEFAULTmacOS builds.
true stops after generating the Xcode project, which is
what the mac-source target delivers. Set by that target rather than by
hand.teamId
public abstract String teamId() default ""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.urlSchemes
public abstract String urlSchemes() default ""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.