Package com.codename1.annotations.buildhints

package com.codename1.annotations.buildhints

Build hints expressed as annotations, so the compiler checks them.

A build hint used to be a codename1.arg.<name>=<value> line in codenameone_settings.properties. Nothing validated it, so a misspelled name was copied into the build request, never read, and silently dropped: the build stayed green and the setting simply did nothing. Written as an annotation the same mistake is an unknown symbol, a wrong value type is a type error, and a value outside a hint's supported set is an unknown enum constant.

Put the annotations on your application's main class:

@Ios(newStorageLocation = Toggle.ON, themeMode = ThemeMode.MODERN)
@Android(themeMode = ThemeMode.MODERN)
@DesktopBuild(titleBar = DesktopTitleBar.NATIVE)
public class MyApplication {
}

These annotations cover the hints most applications set. The rest, and the open-ended families such as android.permission.<NAME> that an annotation cannot express, are still set in codenameone_settings.properties, which continues to work exactly as before. Setting the same hint in both places is a build error.

A project generated recently already runs the goal that turns these into build hints. An older one may not: a goal's default phase does not add an execution to a project, so the annotations would compile and then be ignored. The build refuses rather than shipping without them, and the module that compiles the main class needs:

<execution>
  <id>cn1-process-classes</id>
  <phase>process-classes</phase>
  <goals>
    <goal>process-annotations</goal>
  </goals>
</execution>

These annotations are the source of truth for the hints they expose. Add an attribute here to add a hint: the Java type IS its type, an enum's constants ARE its value domain, and @Hint carries the rest -- the wire key where it differs from the attribute name, the prose the developer guide shows, and whether a cn1lib may append to it.

It does NOT carry what the build server does when a hint is not set. That is the server's to change, and a copy here would be compiled into every app already built against it with no way to follow. An attribute left alone is not written into the request at all -- see HintUnset -- so the server's default is in force rather than merely documented.

Nothing restates any of that. The developer guide's table, the Settings editor's schema and the processor's binding table are all read back out of these classes by BuildHintAnnotationReader; run scripts/gen-build-hint-annotations.sh after editing to refresh them.

A hint with no annotation -- a dynamic family such as android.permission.<NAME>, or one only the build service reads -- is described in maven/build-hint-catalog instead.

  • Class
    Description
    Android
    Android build hints, checked by the compiler.
    AndroidMinSdk
    The Android API level an app runs on at the lowest.
    Build
    Build hints that are not specific to one platform.
    DesktopBuild
    Desktop build hints, checked by the compiler.
    DesktopTitleBar
    Accepted values of the desktop.titleBar build hint.
    HardenControlFlow
    Accepted values of the harden.controlFlow build hint.
    Hardening
    App hardening build hints, checked by the compiler.
    HardenLevel
    Accepted values of the harden.level build hint.
    HardenStrings
    Accepted values of the harden.strings build hint.
    Hint
    What a build hint attribute is, beyond what its Java signature already says.
    HintKind
    What a String build hint really holds.
    HintUnset
    Marks the enum constant that means "nothing was chosen".
    HintValue
    What an enum constant is called on the wire.
    InstallLocation
    Accepted values of the android.installLocation build hint.
    Ios
    iOS build hints, checked by the compiler.
    IosDependencyManager
    Accepted values of the ios.dependencyManager build hint.
    IosPrivacy
    iOS Info.plist privacy usage descriptions.
    IosProjectType
    Accepted values of the ios.project_type build hint.
    OnDeviceDebug
    On-device debugging build hints for iOS and Android.
    ThemeMode
    The look a build asks the platform for.
    Toggle
    A build hint the build server reads as true or false, plus the state of not having said either.