0

Docs: update java_cpp_enum markdown doc

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}
This commit is contained in:
Nate Fischer
2021-07-14 02:14:15 +00:00
committed by Chromium LUCI CQ
parent bd77dcb41d
commit bce81715d4

@ -18,14 +18,15 @@ the Java version.
directive (optional)
* Strip enum entry prefixes to make the generated classes less verbose using
the `GENERATED_JAVA_PREFIX_TO_STRIP` directive (optional)
* Supports
[`@IntDef`](https://developer.android.com/reference/android/support/annotation/IntDef.html)
* Follows best practices by using
[IntDef Instead of Enum](/styleguide/java/java.md#IntDef-Instead-of-Enum)
* Copies comments that directly precede enum entries into the generated Java
class
## Usage
1. Add directives to your C++ enum
1. Add directives to your C++ enum. Only the `GENERATED_JAVA_ENUM_PACKAGE`
directive is required:
```cpp
// GENERATED_JAVA_ENUM_PACKAGE: org.chromium.chrome
@ -38,34 +39,43 @@ class
};
```
2. Add a new build target
2. Add a new build target and add it to the `srcjar_deps` of an
`android_library` target:
```gn
import("//build/config/android/rules.gni")
if (is_android) {
import("//build/config/android/rules.gni")
}
java_cpp_enum("foo_generated_enum") {
sources = [
"base/android/native_foo_header.h",
]
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" ]
}
}
```
3. Add the new target to the desired android_library targets srcjar_deps:
```gn
android_library("base_java") {
srcjar_deps = [
":foo_generated_enum",
]
}
```
4. The generated file `org/chromium/chrome/FooBar.java` would contain:
3. The generated file `org/chromium/chrome/FooBar.java` would contain:
```java
package org.chromium.chrome;
import android.support.annotation.IntDef;
import androidx.annotation.IntDef;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
@ -146,6 +156,40 @@ class
}
```
## Troubleshooting
### Symbol not found/could not resolve IntDef
You may see an error like this when compiling:
```shell
$ 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:
```shell
$ 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.
...
```
## See also
* [Accessing C++ Switches In Java](android_accessing_cpp_switches_in_java.md)
* [Accessing C++ Features In Java](android_accessing_cpp_features_in_java.md)