Annotation Type Hint

@Retention(CLASS) @Target({METHOD,ANNOTATION_TYPE}) public @interface Hint

What a build hint attribute is, beyond what its Java signature already says.

The attribute's type, its name and its enum's constants are the compiler's business and are not restated here. This carries only what javac cannot infer: the wire key when it differs from the attribute name, the prose the developer guide and the Settings editor show, and the handful of facts about how the builders read the value.

The annotation's own default clause is deliberately NOT the build server's default, and nothing here records that either. A hint is written only where the developer set it, so the clause has no meaning at runtime -- see HintUnset for what the default clause does say.

ANNOTATION_TYPE rather than TYPE. This describes a build hint annotation or one of its members, and both are annotation declarations. Allowing TYPE let @Hint(name = "ios.pods") be written straight onto an application class, where it compiles, sets nothing, and reports nothing -- which is the exact silence these annotations exist to remove.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    aliasOf
    The hint this one is a deprecated second spelling of.
    boolean
    appendable
    Whether a cn1lib may append to this hint rather than replace it.
    String
    deprecated
    Why this hint is deprecated, and what to use instead.
    boolean
    enterpriseOnly
    Available only to enterprise accounts.
    boolean
    external
    Documented here but read only by the build service, so nothing in this repository consumes it.
    HintKind
    kind
    What kind of string this is, when the attribute's Java type does not say.
    String
    link
    Further reading, for the guide's table.
    String
    name
    The key this attribute writes, when it is not the group's prefix followed by the attribute name.
    String
    platform
    The platform this hint applies to, for the guide's table.
    String
    separator
    What a list's values are joined with on the wire.
    String
    valuePattern
    A regular expression the value must match, or "" for no check.

  • Element Details

    • name

      String name

      The key this attribute writes, when it is not the group's prefix followed by the attribute name.

      android.min_sdk_version is not minSdkVersion, and the builders are the authority on the spelling.

      Default:
      ""

    • valuePattern

      String valuePattern

      A regular expression the value must match, or "" for no check.

      For the hints whose type cannot express their shape. String says nothing about ios.interface_orientation, whose value is a colon separated list of four known constants -- and a misspelled one does not fail, it just fails to match, so the builder keeps every orientation and the app ships rotating in directions it was told not to.

      Checked by the annotation processor against the value that is about to be written, so it fails the build that declared it rather than the device that runs it. java.util.regex syntax, anchored implicitly: the WHOLE value must match.

      Default:
      ""

    • kind

      HintKind kind

      What kind of string this is, when the attribute's Java type does not say.

      The editor picks its control from this: a version field, a masked field for a secret, a multi-line box for an XML fragment.

      Default:
      DEFAULT

    • appendable

      boolean appendable

      Whether a cn1lib may append to this hint rather than replace it.

      Separate from separator() because the delimiter can legitimately be empty: the XML fragment family -- android.xpermissions and friends -- is appended to with nothing between the pieces, which is not the same as a hint no library can contribute to.

      Default:
      false

    • separator

      String separator

      What a list's values are joined with on the wire.

      A cn1lib appends onto the same key, so this has to match what the builder splits on -- ios.pods is comma delimited and ios.add_libs semicolon delimited.

      Default:
      ""

    • platform

      String platform

      The platform this hint applies to, for the guide's table.

      On the annotation TYPE this is the default for every attribute in it, which is where it belongs: every hint in @Android is an Android hint, and saying so on each of the twenty-four was noise that could also be got wrong. An attribute states it only to disagree -- @OnDeviceDebug spans two platforms and each of its attributes says which.

      Default:
      ""

    • aliasOf

      String aliasOf

      The hint this one is a deprecated second spelling of.

      Both names denote ONE effective setting -- the builder reads android.captureRecord and then lets and.captureRecord override it -- so conflict detection has to collapse them.

      Default:
      ""

    • deprecated

      String deprecated
      Why this hint is deprecated, and what to use instead.
      Default:
      ""

    • external

      boolean external
      Documented here but read only by the build service, so nothing in this repository consumes it.
      Default:
      false

    • enterpriseOnly

      boolean enterpriseOnly
      Available only to enterprise accounts.
      Default:
      false

    • link

      String link
      Further reading, for the guide's table.
      Default:
      ""