How are .java files in android_stubs_current_intermediates directory generated?

Question

The Android build process generates(?) Java stubs for each of the classes in the android.jar, and stores them in the following directory:

./out/target/common/obj/JAVA_LIBRARIES/android_stubs_current_intermediates/src/

For example, the subdirectory java/lang/ of the above directory contains .java files corresponding to java.lang.* classes, and the subdirectory `android/app/' contains .java files corresponding to android.app.* classes. These .java files dont contain actual code, but just signatures with dummy bodies.

I am assuming that those .java files are generated from the actual source code using a tool. My question is, which is this tool, and is it usable outside of the Android build process?

I want to use that tool to generate stubs for non-Android Java classes.

Answer 1

The "stubs" here is the framework API stub generated by running javadoc tool.

In most cases, when we talk about stub file in Android, we mean the java file generated by aidl tool. For example see How to generate stub in android? - Stack Overflow

In particular, the Android build system contains a makefile called droiddoc.mk that can be used to generate documentation, java API stubs and API xml files, which actually calls javadoc.
droiddoc.mk is under build/core. In build/core/config.mk there is a variable named BUILD_DROIDDOC to make it easier to include the droiddoc.mk.

Look at the droiddoc.mk, it calls javadoc:

javadoc \
            \@$(PRIVATE_SRC_LIST_FILE) \
            -J-Xmx1280m \
            $(PRIVATE_PROFILING_OPTIONS) \
            -quiet \
            -doclet com.google.doclava.Doclava \
            -docletpath $(PRIVATE_DOCLETPATH) \
            -templatedir $(PRIVATE_CUSTOM_TEMPLATE_DIR) \
            $(PRIVATE_DROIDDOC_HTML_DIR) \
            $(addprefix -bootclasspath ,$(PRIVATE_BOOTCLASSPATH)) \
            $(addprefix -classpath ,$(PRIVATE_CLASSPATH)) \
            -sourcepath $(PRIVATE_SOURCE_PATH)$(addprefix :,$(PRIVATE_CLASSPATH)) \
            -d $(PRIVATE_OUT_DIR) \
            $(PRIVATE_CURRENT_BUILD) $(PRIVATE_CURRENT_TIME) \
            $(PRIVATE_DROIDDOC_OPTIONS) \
    && touch -f $@ 

There is nothing about the stub right? Don't worry, notice that there is a PRIVATE_DROIDDOC_OPTIONS variable, and

PRIVATE_DROIDDOC_OPTIONS := $(LOCAL_DROIDDOC_OPTIONS)

Many Android.mk files in AOSP, for example the framework/base/Android.mk, contain the include $(BUILD_DROIDDOC) to generate docs. In framework/base/Android.mk, there is a piece of code:

LOCAL_DROIDDOC_OPTIONS:=\
                $(framework_docs_LOCAL_DROIDDOC_OPTIONS) \
                -stubs $(TARGET_OUT_COMMON_INTERMEDIATES)/JAVA_LIBRARIES/android_stubs_current_intermediates/src \
                -api $(INTERNAL_PLATFORM_API_FILE) \
                -nodocs

LOCAL_DROIDDOC_CUSTOM_TEMPLATE_DIR:=build/tools/droiddoc/templates-sdk

LOCAL_UNINSTALLABLE_MODULE := true

include $(BUILD_DROIDDOC)

The LOCAL_DROIDDOC_OPTIONS contains a -stubs option. And it will finally put into the javadoc command used by droiddoc.mk.

However, we may notice that the javadoc doesn't contain any option like -stubs. The key is that you can customize the content and format of the Javadoc tool's output by using doclets. The Javadoc tool has a default "built-in" doclet, called the standard doclet, that generates HTML-formatted API documentation. You can modify or subclass the standard doclet, or write your own doclet to generate HTML, XML, MIF, RTF or whatever output format you'd like.

We can use the -doclet option to specify our customized doclet. And the javadoc command in droiddoc.mk use the -doclet com.google.doclava.Doclava. That doclet receives the -stubs option.

Look at the Doclava implementation under external/doclava/src/com/google/doclava/Doclava.java

  else if (a[0].equals("-stubs")) {
    stubsDir = a[1];
  } else if (a[0].equals("-stubpackages")) {
    stubPackages = new HashSet<String>();
    for (String pkg : a[1].split(":")) {
      stubPackages.add(pkg);
    }
  }

It receives the -stubs option. And here is how it process the stubsDir.

// Stubs
if (stubsDir != null || apiFile != null || proguardFile != null) {
  Stubs.writeStubsAndApi(stubsDir, apiFile, proguardFile, stubPackages);
}

And trace the implementation of the Stubs.writeStubsAndApi, you can see why the content in the stub files are like that.

You can even write your own java files and generate your stubs like what the test cases under build/tools/droiddoc/test.