Update D8 javadoc and add an R8 javadoc target.
Change-Id: Iff2bbc36a8b242ba3bbbccc1388a221dea57f4b3
diff --git a/build.gradle b/build.gradle
index dc149c5..4e7562c 100644
--- a/build.gradle
+++ b/build.gradle
@@ -1680,22 +1680,58 @@
}
task javadocD8(type: Javadoc) {
+ title "D8 API"
classpath = sourceSets.main.compileClasspath
source = sourceSets.main.allJava
include '**/com/android/tools/r8/ArchiveClassFileProvider.java'
+ include '**/com/android/tools/r8/ArchiveProgramResourceProvider.java'
include '**/com/android/tools/r8/BaseCommand.java'
- include '**/com/android/tools/r8/BaseOutput.java'
+ include '**/com/android/tools/r8/BaseCompilerCommand.java'
include '**/com/android/tools/r8/ClassFileResourceProvider.java'
include '**/com/android/tools/r8/CompilationFailedException.java'
include '**/com/android/tools/r8/CompilationMode.java'
include '**/com/android/tools/r8/D8.java'
include '**/com/android/tools/r8/D8Command.java'
- include '**/com/android/tools/r8/D8Output.java'
+ include '**/com/android/tools/r8/DexIndexedConsumer.java'
+ include '**/com/android/tools/r8/DexFilePerClassFileConsumer.java'
include '**/com/android/tools/r8/Diagnostic.java'
include '**/com/android/tools/r8/DiagnosticsHandler.java'
- include '**/com/android/tools/r8/Location.java'
+ include '**/com/android/tools/r8/ProgramConsumer.java'
+ include '**/com/android/tools/r8/ProgramResource.java'
+ include '**/com/android/tools/r8/ProgramResourceProvider.java'
include '**/com/android/tools/r8/Resource.java'
- include '**/com/android/tools/r8/TextRangeLocation.java'
+ include '**/com/android/tools/r8/ResourceException.java'
+ include '**/com/android/tools/r8/StringConsumer.java'
+ include '**/com/android/tools/r8/StringResource.java'
+ include '**/com/android/tools/r8/Version.java'
+ include '**/com/android/tools/r8/origin/*.java'
+}
+
+task javadocR8(type: Javadoc) {
+ title "R8 API"
+ classpath = sourceSets.main.compileClasspath
+ source = sourceSets.main.allJava
+ include '**/com/android/tools/r8/ArchiveClassFileProvider.java'
+ include '**/com/android/tools/r8/ArchiveProgramResourceProvider.java'
+ include '**/com/android/tools/r8/BaseCommand.java'
+ include '**/com/android/tools/r8/BaseCompilerCommand.java'
+ include '**/com/android/tools/r8/ClassFileConsumer.java'
+ include '**/com/android/tools/r8/ClassFileResourceProvider.java'
+ include '**/com/android/tools/r8/CompilationFailedException.java'
+ include '**/com/android/tools/r8/CompilationMode.java'
+ include '**/com/android/tools/r8/R8.java'
+ include '**/com/android/tools/r8/R8Command.java'
+ include '**/com/android/tools/r8/DexIndexedConsumer.java'
+ include '**/com/android/tools/r8/Diagnostic.java'
+ include '**/com/android/tools/r8/DiagnosticsHandler.java'
+ include '**/com/android/tools/r8/ProgramConsumer.java'
+ include '**/com/android/tools/r8/ProgramResource.java'
+ include '**/com/android/tools/r8/ProgramResourceProvider.java'
+ include '**/com/android/tools/r8/Resource.java'
+ include '**/com/android/tools/r8/ResourceException.java'
+ include '**/com/android/tools/r8/StringConsumer.java'
+ include '**/com/android/tools/r8/StringResource.java'
+ include '**/com/android/tools/r8/Version.java'
include '**/com/android/tools/r8/origin/*.java'
}
diff --git a/src/main/java/com/android/tools/r8/BaseCommand.java b/src/main/java/com/android/tools/r8/BaseCommand.java
index 10c92dc..fe26162 100644
--- a/src/main/java/com/android/tools/r8/BaseCommand.java
+++ b/src/main/java/com/android/tools/r8/BaseCommand.java
@@ -23,9 +23,9 @@
/**
* Base class for commands and command builders for applications/tools which take an Android
- * application (and a main-dex list) as input.
+ * application sources (and optional main-dex list) as input.
*/
-abstract class BaseCommand {
+public abstract class BaseCommand {
private final boolean printHelp;
private final boolean printVersion;
diff --git a/src/main/java/com/android/tools/r8/BaseCompilerCommand.java b/src/main/java/com/android/tools/r8/BaseCompilerCommand.java
index 4ea102b..f42353a 100644
--- a/src/main/java/com/android/tools/r8/BaseCompilerCommand.java
+++ b/src/main/java/com/android/tools/r8/BaseCompilerCommand.java
@@ -17,12 +17,13 @@
/**
* Base class for commands and command builders for compiler applications/tools which besides an
- * Android application (and a main-dex list) also takes compilation output, compilation mode and
- * min API level as input.
+ * Android application (and optional main-dex list) also configure compilation output, compilation
+ * mode and min API level.
*/
-abstract class BaseCompilerCommand extends BaseCommand {
+public abstract class BaseCompilerCommand extends BaseCommand {
// TODO(b/70656566): Remove this once the deprecated API is removed.
+ @Deprecated
protected static class OutputOptions {
final Path path;
final OutputMode mode;
diff --git a/src/main/java/com/android/tools/r8/D8.java b/src/main/java/com/android/tools/r8/D8.java
index fca359f..f10bd31 100644
--- a/src/main/java/com/android/tools/r8/D8.java
+++ b/src/main/java/com/android/tools/r8/D8.java
@@ -44,7 +44,7 @@
* <pre>
* D8.run(D8Command.builder()
* .addProgramFiles(inputPathA, inputPathB)
- * .setOutputPath(outputPath)
+ * .setOutput(outputPath, OutputMode.DexIndexed)
* .build());
* </pre>
*
@@ -80,10 +80,7 @@
}
/**
- * Main API entry for the D8 dexer.
- *
- * <p>The D8 dexer API is intentionally limited and should "do the right thing" given a set of
- * inputs. If the API does not suffice please contact the R8 team.
+ * Main API entry for the D8 dexer with a externally supplied executor service.
*
* @param command D8 command.
* @param executor executor service from which to get threads for multi-threaded processing.
diff --git a/src/main/java/com/android/tools/r8/D8Command.java b/src/main/java/com/android/tools/r8/D8Command.java
index fece59d..211c65c 100644
--- a/src/main/java/com/android/tools/r8/D8Command.java
+++ b/src/main/java/com/android/tools/r8/D8Command.java
@@ -28,6 +28,7 @@
* D8Command command = D8Command.builder()
* .addProgramFiles(path1, path2)
* .setMode(CompilationMode.RELEASE)
+ * .setOutput(Paths.get("output.zip", OutputMode.DexIndexed))
* .build();
* </pre>
*/
diff --git a/src/main/java/com/android/tools/r8/R8.java b/src/main/java/com/android/tools/r8/R8.java
index 304dde3..dc6ebee 100644
--- a/src/main/java/com/android/tools/r8/R8.java
+++ b/src/main/java/com/android/tools/r8/R8.java
@@ -72,6 +72,35 @@
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
+/**
+ * The R8 compiler.
+ *
+ * <p>R8 performs whole-program optimizing compilation of Java bytecode. It supports compilation of
+ * Java bytecode to Java bytecode or DEX bytecode. R8 supports tree-shaking the program to remove
+ * unneeded code and it supports minification of the program names to reduce the size of the
+ * resulting program.
+ *
+ * <p>The R8 API is intentionally limited and should "do the right thing" given a command. If this
+ * API does not suffice please contact the D8/R8 team.
+ *
+ * <p>R8 supports some configuration using configuration files mostly compatible with the format of
+ * the <a href="https://www.guardsquare.com/en/proguard">ProGuard</a> optimizer.
+ *
+ * <p>The compiler is invoked by calling {@link #run(R8Command) R8.run} with an appropriate {@link
+ * R8Command}. For example:
+ *
+ * <pre>
+ * R8.run(R8Command.builder()
+ * .addProgramFiles(inputPathA, inputPathB)
+ * .addLibraryFiles(androidJar)
+ * .setOutput(outputPath, OutputMode.DexIndexed)
+ * .build());
+ * </pre>
+ *
+ * The above reads the input files denoted by {@code inputPathA} and {@code inputPathB}, compiles
+ * them to DEX bytecode, using {@code androidJar} as the reference of the system runtime library,
+ * and then writes the result to the directory or zip archive specified by {@code outputPath}.
+ */
public class R8 {
private final Timing timing = new Timing("R8");
@@ -82,6 +111,49 @@
options.itemFactory.resetSortedIndices();
}
+ /**
+ * Main API entry for the R8 compiler.
+ *
+ * <p>The R8 API is intentionally limited and should "do the right thing" given a command. If this
+ * API does not suffice please contact the R8 team.
+ *
+ * @param command R8 command.
+ */
+ public static void run(R8Command command) throws CompilationFailedException {
+ AndroidApp app = command.getInputApp();
+ InternalOptions options = command.getInternalOptions();
+ ExecutorService executor = ThreadUtils.getExecutorService(options);
+ ExceptionUtils.withR8CompilationHandler(
+ command.getReporter(),
+ () -> {
+ try {
+ run(app, options, executor);
+ } finally {
+ executor.shutdown();
+ }
+ });
+ }
+
+ /**
+ * Main API entry for the R8 compiler.
+ *
+ * <p>The R8 API is intentionally limited and should "do the right thing" given a command. If this
+ * API does not suffice please contact the R8 team.
+ *
+ * @param command R8 command.
+ * @param executor executor service from which to get threads for multi-threaded processing.
+ */
+ public static void run(R8Command command, ExecutorService executor)
+ throws CompilationFailedException {
+ AndroidApp app = command.getInputApp();
+ InternalOptions options = command.getInternalOptions();
+ ExceptionUtils.withR8CompilationHandler(
+ command.getReporter(),
+ () -> {
+ run(app, options, executor);
+ });
+ }
+
// Compute the marker to be placed in the main dex file.
private static Marker getMarker(InternalOptions options) {
if (options.hasMarker()) {
@@ -424,49 +496,6 @@
}
}
- /**
- * Main API entry for the R8 compiler.
- *
- * <p>The R8 API is intentionally limited and should "do the right thing" given a command. If this
- * API does not suffice please contact the R8 team.
- *
- * @param command R8 command.
- */
- public static void run(R8Command command) throws CompilationFailedException {
- AndroidApp app = command.getInputApp();
- InternalOptions options = command.getInternalOptions();
- ExecutorService executor = ThreadUtils.getExecutorService(options);
- ExceptionUtils.withR8CompilationHandler(
- command.getReporter(),
- () -> {
- try {
- run(app, options, executor);
- } finally {
- executor.shutdown();
- }
- });
- }
-
- /**
- * Main API entry for the R8 compiler.
- *
- * <p>The R8 API is intentionally limited and should "do the right thing" given a command. If this
- * API does not suffice please contact the R8 team.
- *
- * @param command R8 command.
- * @param executor executor service from which to get threads for multi-threaded processing.
- */
- public static void run(R8Command command, ExecutorService executor)
- throws CompilationFailedException {
- AndroidApp app = command.getInputApp();
- InternalOptions options = command.getInternalOptions();
- ExceptionUtils.withR8CompilationHandler(
- command.getReporter(),
- () -> {
- run(app, options, executor);
- });
- }
-
/** TODO(sgjesse): Get rid of this. */
public static AndroidApp runInternal(R8Command command) throws IOException, CompilationException {
InternalOptions options = command.getInternalOptions();
diff --git a/src/main/java/com/android/tools/r8/Version.java b/src/main/java/com/android/tools/r8/Version.java
index 0e6c94d..f4056e7 100644
--- a/src/main/java/com/android/tools/r8/Version.java
+++ b/src/main/java/com/android/tools/r8/Version.java
@@ -6,6 +6,7 @@
import com.android.tools.r8.utils.VersionProperties;
+/** Version of the D8/R8 library. */
public final class Version {
// This field is accessed from release scripts using simple pattern matching.
@@ -20,6 +21,7 @@
System.out.println(VersionProperties.INSTANCE.getDescription());
}
+ /** Is this a development version of the D8/R8 library. */
public static boolean isDev() {
return LABEL.endsWith("-dev") || VersionProperties.INSTANCE.isEngineering();
}
diff --git a/src/test/java/com/android/tools/r8/TestBase.java b/src/test/java/com/android/tools/r8/TestBase.java
index 3af239f..fd238f3 100644
--- a/src/test/java/com/android/tools/r8/TestBase.java
+++ b/src/test/java/com/android/tools/r8/TestBase.java
@@ -277,16 +277,16 @@
}
/**
- * Generate a Proguard configuration for keeping the "public static void main(String[])" method
- * of the specified class.
+ * Generate a Proguard configuration for keeping the "public static void main(String[])" method of
+ * the specified class.
*/
public static String keepMainProguardConfiguration(Class clazz) {
return keepMainProguardConfiguration(clazz.getCanonicalName());
}
/**
- * Generate a Proguard configuration for keeping the "public static void main(String[])" method
- * of the specified class.
+ * Generate a Proguard configuration for keeping the "public static void main(String[])" method of
+ * the specified class.
*/
public static String keepMainProguardConfiguration(String clazz) {
return "-keep public class " + clazz + " {\n"
@@ -296,9 +296,9 @@
}
/**
- * Generate a Proguard configuration for keeping the "public static void main(String[])" method
- * of the specified class and specify if -allowaccessmodification and -dontobfuscate are added
- * as well.
+ * Generate a Proguard configuration for keeping the "public static void main(String[])" method of
+ * the specified class and specify if -allowaccessmodification and -dontobfuscate are added as
+ * well.
*/
public static String keepMainProguardConfiguration(
Class clazz, boolean allowaccessmodification, boolean obfuscate) {
