src/docs/android_accessing_cpp_switches_in_java.md

Accessing C++ Switches In Java

[TOC]

Introduction

Accessing C++ switches in Java is implemented via a Python script which analyzes the C++ switches file and generates the corresponding Java class, based on a template file. The template file must be specified in the GN target.

Usage

1. Create a template file (ex. FooSwitches.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 command line switches that are specific to the foo project.
     */
    public final class FooSwitches {{
   
    {NATIVE_STRINGS}
   
        // Prevents instantiation.
        private FooSwitches() {{}}
    }}
   

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_strings("java_switches_srcjar") {
       # External code should depend on ":foo_java" instead.
       visibility = [ ":*" ]
       sources = [
         "//base/android/foo_switches.cc",
       ]
       template = "//base/android/java_templates/FooSwitches.java.tmpl"
     }
   
     # If there's already an android_library target, you can add
     # java_switches_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_switches_srcjar" ]
     }
   }
   

3. The generated file out/Default/gen/.../org/chromium/foo/FooSwitches.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;
   
   /**
    * Contains command line switches that are specific to the foo project.
    */
   public final class FooSwitches {
   
       // ...snip...
   
       // This following string constants were inserted by
       //     java_cpp_strings.py
       // From
       //     ../../base/android/foo_switches.cc
       // Into
       //     ../../base/android/java_templates/FooSwitches.java.tmpl
   
       // Documentation for the C++ switch is copied here.
       public static final String SOME_SWITCH = "some-switch";
   
       // ...snip...
   
       // Prevents instantiation.
       private FooSwitches() {}
   }
   

See also

• Accessing C++ Enums In Java
• Accessing C++ Features In Java

Code

• Generator code and Tests
• GN template