0
Files
src/docs/android_accessing_cpp_features_in_java.md
Daniel Cheng dc644a135d Add BASE_FEATURE() / BASE_DECLARE_FEATURE() macros for defining features
There are subtle requirements around declaring and defining
base::Features. In addition, these requirements also evolve over time:
updating the various uses requires updating an estimated 6000+ uses.

Introduce helper macros modelled after absl's ABSL_FLAG() and
ABSL_DECLARE_FLAG() macros instead; in the future, base::Feature may
even become an internal implementation detail.

This also simplifies the helper script for autogenerating Java features
from C++ features, as it no longer needs to try to accommodate all
potential reorderings of `CONSTINIT`, `const`, and export macros.

Bug: 1364289
Change-Id: Id88f7c4a60efa28cdab36accb4d8386ec84ea3e4
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3902697
Reviewed-by: Egor Pasko <pasko@chromium.org>
Reviewed-by: Alexei Svitkine <asvitkine@chromium.org>
Commit-Queue: Daniel Cheng <dcheng@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1048852}
2022-09-19 23:21:37 +00:00

5.6 KiB

Accessing C++ Features In Java

[TOC]

Introduction

Accessing C++ base::Features in Java is implemented via a Python script which analyzes the *_features.cc file and generates the corresponding Java class, based on a template file. The template file must be specified in the GN target. This outputs Java String constants which represent the name of the base::Feature.

Usage

  1. Create a template file (ex. FooFeatures.java.tmpl). Change "Copyright 2020" to be whatever the year is at the time of writing (as you would for any other file).

     // Copyright 2020 The Chromium Authors
     // Use of this source code is governed by a BSD-style license that can be
     // found in the LICENSE file.
    
     package org.chromium.foo;
    
     // Be sure to escape any curly braces in your template by doubling as
     // follows.
     /**
      * Contains features that are specific to the foo project.
      */
     public final class FooFeatures {{
    
     {NATIVE_FEATURES}
    
         // Prevents instantiation.
         private FooFeatures() {{}}
     }}
    
  2. Add a new build target and add it to the srcjar_deps of an android_library target:

    if (is_android) {
      import("//build/config/android/rules.gni")
    }
    
    if (is_android) {
      java_cpp_features("java_features_srcjar") {
        # External code should depend on ":foo_java" instead.
        visibility = [ ":*" ]
        sources = [
          "//base/android/foo_features.cc",
        ]
        template = "//base/android/java_templates/FooFeatures.java.tmpl"
      }
    
      # If there's already an android_library target, you can add
      # java_features_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_features_srcjar" ]
      }
    }
    
  3. Add a deps entry to "common_java" in "//android_webview/BUILD.gn" if creating a new android_library in the previous step:

    android_library("common_java") {
      ...
    
      deps = [
        ...
        "//path/to:foo_java",
        ...
      ]
    }
    
  4. The generated file out/Default/gen/.../org/chromium/foo/FooFeatures.java would contain:

    // Copyright $YEAR The Chromium Authors
    // Use of this source code is governed by a BSD-style license that can be
    // found in the LICENSE file.
    
    package org.chromium.foo;
    
    // Be sure to escape any curly braces in your template by doubling as
    // follows.
    /**
     * Contains features that are specific to the foo project.
     */
    public final class FooFeatures {
    
        // This following string constants were inserted by
        //     java_cpp_features.py
        // From
        //     ../../base/android/foo_features.cc
        // Into
        //     ../../base/android/java_templates/FooFeatures.java.tmpl
    
        // Documentation for the C++ Feature is copied here.
        public static final String SOME_FEATURE = "SomeFeature";
    
        // ...snip...
    
        // Prevents instantiation.
        private FooFeatures() {}
    }
    

Troubleshooting

The script only supports limited syntaxes for declaring C++ base::Features. You may see an error like the following during compilation:

...
org/chromium/foo/FooFeatures.java:41: error: duplicate declaration of field: MY_FEATURE
    public static final String MY_FEATURE = "MyFeature";

This can happen if you've re-declared a feature for mutually-exclsuive build configs (ex. the feature is enabled-by-default for one config, but disabled-by-default for another). Example:

#if defined(...)
BASE_FEATURE(kMyFeature, "MyFeature", base::FEATURE_ENABLED_BY_DEFAULT);
#else
BASE_FEATURE(kMyFeature, "MyFeature", base::FEATURE_DISABLED_BY_DEFAULT);
#endif

The java_cpp_features rule doesn't know how to evaluate C++ preprocessor directives, so it generates two identical Java fields (which is what the compilation error is complaining about). Fortunately, the workaround is fairly simple. Rewrite the definition to only use directives around the enabled state:

BASE_FEATURE(kMyFeature,
             "MyFeature",
#if defined(...)
             base::FEATURE_ENABLED_BY_DEFAULT
#else
             base::FEATURE_DISABLED_BY_DEFAULT
#endif
};

Checking if a Feature is enabled

The standard pattern is to create a FooFeatureList.java class with an isEnabled() method (ex. ContentFeatureList). This should call into C++ (ex. content_feature_list), where a subset of features are exposed via the kFeaturesExposedToJava array. You can either add your base::Feature to an existing feature_list or create a new FeatureList class if no existing one is suitable. Then you can check the enabled state like so:

// It's OK if ContentFeatureList checks FooFeatures.*, so long as
// content_feature_list.cc exposes `kMyFeature`.
if (ContentFeatureList.isEnabled(FooFeatures.MY_FEATURE)) {
    // ...
}

At the moment, base::Features must be explicitly exposed to Java this way, in whichever layer needs to access their state. See https://crbug.com/1060097.

See also

Code