
No change to logic. This updates the doc for java_cpp_enum: * Explains how to correctly include //third_party/androidx:androidx_annotation_annotation_java in the dependencies * Updates the doc to use androidx.annotation.IntDef instead of the legacy android.support package name * Consolidates two steps for easier copy-pasting and consistency with the docs for java_cpp_features and java_cpp_switches * Adds some troubleshooting steps in case the reader hits build errors Test: I followed these steps to add a new java_cpp_enum rule Test: review content: upload to gerrit > open file > click "gitiles" Change-Id: Ib2de0d5be6a4b04a9efc101d8a3b52ee5ffaa471 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3025844 Commit-Queue: Nate Fischer <ntfschr@chromium.org> Auto-Submit: Nate Fischer <ntfschr@chromium.org> Reviewed-by: Andrew Grieve <agrieve@chromium.org> Cr-Commit-Position: refs/heads/master@{#901323}
5.8 KiB
Accessing C++ Enums In Java
[TOC]
Introduction
Accessing C++ enums in Java is implemented via a Python script which analyzes the C++ enum and spits out the corresponding Java class. The enum needs to be annotated in a particular way. By default, the generated class name will be the same as the name of the enum. If all the names of the enum values are prefixed with the MACRO_CASED_ name of the enum those prefixes will be stripped from the Java version.
Features
- Customize the package name of the generated class using the
GENERATED_JAVA_ENUM_PACKAGE
directive (required) - Customize the class name using the
GENERATED_JAVA_CLASS_NAME_OVERRIDE
directive (optional) - Strip enum entry prefixes to make the generated classes less verbose using
the
GENERATED_JAVA_PREFIX_TO_STRIP
directive (optional) - Follows best practices by using IntDef Instead of Enum
- Copies comments that directly precede enum entries into the generated Java class
Usage
-
Add directives to your C++ enum. Only the
GENERATED_JAVA_ENUM_PACKAGE
directive is required:// GENERATED_JAVA_ENUM_PACKAGE: org.chromium.chrome // GENERATED_JAVA_CLASS_NAME_OVERRIDE: FooBar // GENERATED_JAVA_PREFIX_TO_STRIP: BAR_ enum SomeEnum { BAR_A, BAR_B, BAR_C = BAR_B, };
-
Add a new build target and add it to the
srcjar_deps
of anandroid_library
target:if (is_android) { import("//build/config/android/rules.gni") } if (is_android) { java_cpp_enum("java_enum_srcjar") { # External code should depend on ":foo_java" instead. visibility = [ ":*" ] sources = [ # Include the .h or .cc file(s) which defines the enum(s). "base/android/native_foo_header.h", ] } # If there's already an android_library target, you can add # java_enum_srcjar to that target's srcjar_deps. Otherwise, the best # practice is to create a new android_library just for this target. android_library("foo_java") { srcjar_deps = [ ":java_enum_srcjar" ] # Important: the generated enum uses the @IntDef annotation provided by # this dependency. deps = [ "//third_party/androidx:androidx_annotation_annotation_java" ] } }
-
The generated file
org/chromium/chrome/FooBar.java
would contain:package org.chromium.chrome; import androidx.annotation.IntDef; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; @IntDef({ FooBar.A, FooBar.B, FooBar.C }) @Retention(RetentionPolicy.SOURCE) public @interface FooBar { int A = 0; int B = 1; int C = 1; }
Formatting Notes
-
Handling long package names:
// GENERATED_JAVA_ENUM_PACKAGE: ( // org.chromium.chrome.this.package.is.too.long.to.fit.on.a.single.line)
-
Enum entries
-
Single line enums should look like this:
// GENERATED_JAVA_ENUM_PACKAGE: org.foo enum NotificationActionType { BUTTON, TEXT };
-
Multi-line enums should have one enum entry per line, like this:
// GENERATED_JAVA_ENUM_PACKAGE: org.foo enum NotificationActionType { BUTTON, TEXT };
-
Multi-line enum entries are allowed but should be formatted like this:
// GENERATED_JAVA_ENUM_PACKAGE: org.foo enum NotificationActionType { LongKeyNumberOne, LongKeyNumberTwo, ... LongKeyNumberThree = LongKeyNumberOne | LongKeyNumberTwo | ... };
-
-
Preserving comments
// GENERATED_JAVA_ENUM_PACKAGE: org.chromium enum CommentEnum { // This comment will be preserved. ONE, TWO, // This comment will NOT be preserved. THREE }
... public @interface CommentEnum { ... /** * This comment will be preserved. */ int ONE = 0; int TWO = 1; int THREE = 2; }
Troubleshooting
Symbol not found/could not resolve IntDef
You may see an error like this when compiling:
$ autoninja -C out/Default base/foo_java
util.build_utils.CalledProcessError: Command failed: ...
org/chromium/chrome/FooBar.java:13: error: symbol not found androidx.annotation.IntDef
Please add //third_party/androidx:androidx_annotation_annotation_java dep to //base/foo_java. File a crbug if this suggestion is incorrect.
import androidx.annotation.IntDef;
^
org/chromium/chrome/FooBar.java:18: error: could not resolve IntDef
@IntDef({
^
The fix is to add
"//third_party/androidx:androidx_annotation_annotation_java"
to the deps
of
the android_library
. Note: do not add this to the java_cpp_enum
target
by mistake, otherwise you'll see a new error:
$ autoninja -C out/Default base/foo_java
[0/1] Regenerating ninja files
ERROR at //base/BUILD.gn:194:12: Assignment had no effect.
deps = [ "//third_party/androidx:androidx_annotation_annotation_java" ]
^--------------------------------------------------------------
You set the variable "deps" here and it was unused before it went
out of scope.
...