# 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.

- Related Packages
  Package
  Description
  com.codename1.annotations
  Codename One specific Java annotations used by the build pipeline and the ParparVM bytecode translator to mark methods and classes for special treatment -- e.g.
  com.codename1.annotations.graphql
  Annotations for declaring type safe GraphQL clients.
  com.codename1.annotations.grpc
  gRPC-Web client annotations.
  com.codename1.annotations.rest
  Annotations for declaring type safe REST clients.
- 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.
  FileAccess
  How a sandboxed macOS application may reach files the user chooses.
  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.
  Mac
  Native macOS build hints, checked by the compiler.
  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.