chromium/src
0
Fork 0
Code Activity
Files
bc31655139ec8d245918376228686656c4747e84
src/docs/android_accessing_cpp_switches_in_java.md
Nate Fischer 9320324617 Docs: fix documentation for java_cpp_strings 
No change to logic, only docs.

This fixes several mistakes in the java_cpp_strings docs:
 * Do not need GENERATED_JAVA_PACKAGE
 * {NATIVE_STRINGS}, not {NATIVE_SWITCHES}
 * Do not need "This file is autogenerated..." boilerplate in the
   template
 * Consistent package name between template and generated file
 * Consistent class name between template and generated file
 * Change {YEAR} to $YEAR, as this must not be left templated, but
   should be filled in by the author

This also adds some more opinionated changes:
 * Mark the class as "public final" not "public abstract" and mark the
   constructor private, as this is a more robust way to mark the class
   as non-instantiable
 * Include the boilerplate "This following string constants..." [sic]
   message in the generated file, as that's what the script inserts.
 * Use more realistic file names (foo_switches.cc and FooSwitches.java).
 * Add javadoc for the template file, as a suggestion for others to
   document the generated class.

Bug: 1011991
Test: tools/md_browser/md_browser.py
Test: Upload to gerrit > open file > click "gitiles"
Change-Id: Ia1aa96cf50842bf226f35440fd2cafe8a186f8b5
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1863866
Reviewed-by: Ian Vollick <vollick@chromium.org>
Commit-Queue: Nate Fischer <ntfschr@chromium.org>
Cr-Commit-Position: refs/heads/master@{#706456}
2019-10-16 15:31:58 +00:00

2.7 KiB
Raw Blame History

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 spits out the corresponding Java class. The generated class name will be based upon the switch file name, and the path must be specified in a comment within the switch file itself.

Usage

  1. Create a template file (ex. FooSwitches.java.tmpl)

     // Copyright $YEAR The Chromium Authors. All rights reserved.
 // 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

    import("//build/config/android/rules.gni")

java_cpp_strings("java_switches") {
  sources = [
    "//base/android/foo_switches.cc",
  ]
  template = "//base/android/java_templates/FooSwitches.java.tmpl"
}

  3. Add the new target to the desired android_library targets srcjar_deps:

    android_library("base_java") {
  srcjar_deps = [
    ":java_switches",
  ]
}

  4. The generated file out/Default/gen/.../org/chromium/foo/FooSwitches.java would contain:

    // Copyright $YEAR The Chromium Authors. All rights reserved.
// 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() {}
}

Code