Add module type docs to the java package
Add some overview of the java module types so that we have something
to display in the autogenerated docs.
Bug: 67909957
Test: m soong_docs
Change-Id: I3594dd550f8272f4418f3ea12cded4083674809b
diff --git a/java/aar.go b/java/aar.go
index 7495bda..60fbe29 100644
--- a/java/aar.go
+++ b/java/aar.go
@@ -367,6 +367,12 @@
a.exportedStaticPackages = android.FirstUniquePaths(a.exportedStaticPackages)
}
+// android_library builds and links sources into a `.jar` file for the device along with Android resources.
+//
+// An android_library has a single variant that produces a `.jar` file containing `.class` files that were
+// compiled against the device bootclasspath, along with a `package-res.apk` file containing Android resources compiled
+// with aapt2. This module is not suitable for installing on a device, but can be used as a `static_libs` dependency of
+// an android_app module.
func AndroidLibraryFactory() android.Module {
module := &AndroidLibrary{}
@@ -584,6 +590,10 @@
var _ android.PrebuiltInterface = (*Import)(nil)
+// android_library_import imports an `.aar` file into the build graph as if it was built with android_library.
+//
+// This module is not suitable for installing on a device, but can be used as a `static_libs` dependency of
+// an android_app module.
func AARImportFactory() android.Module {
module := &AARImport{}
diff --git a/java/app.go b/java/app.go
index 05d1927..3cb7e8e 100644
--- a/java/app.go
+++ b/java/app.go
@@ -395,6 +395,7 @@
return String(a.appProperties.Certificate)
}
+// android_app compiles sources and Android resources into an Android application package `.apk` file.
func AndroidAppFactory() android.Module {
module := &AndroidApp{}
@@ -457,6 +458,8 @@
}
}
+// android_test compiles test sources and Android resources into an Android application package `.apk` file and
+// creates an `AndroidTest.xml` file to allow running the test with `atest` or a `TEST_MAPPING` file.
func AndroidTestFactory() android.Module {
module := &AndroidTest{}
@@ -494,6 +497,9 @@
appTestHelperAppProperties appTestHelperAppProperties
}
+// android_test_helper_app compiles sources and Android resources into an Android application package `.apk` file that
+// will be used by tests, but does not produce an `AndroidTest.xml` file so the module will not be run directly as a
+// test.
func AndroidTestHelperAppFactory() android.Module {
module := &AndroidTestHelperApp{}
@@ -528,6 +534,8 @@
Certificate *string
}
+// android_app_certificate modules can be referenced by the certificates property of android_app modules to select
+// the signing key.
func AndroidAppCertificateFactory() android.Module {
module := &AndroidAppCertificate{}
module.AddProperties(&module.properties)
diff --git a/java/genrule.go b/java/genrule.go
index 8f29482..25494ec 100644
--- a/java/genrule.go
+++ b/java/genrule.go
@@ -25,8 +25,37 @@
}
// java_genrule is a genrule that can depend on other java_* objects.
-// The cmd may be run multiple times, once for each of the different host/device
-// variations.
+//
+// By default a java_genrule has a single variant that will run against the device variant of its dependencies and
+// produce an output that can be used as an input to a device java rule.
+//
+// Specifying `host_supported: true` will produce two variants, one that uses device dependencie sand one that uses
+// host dependencies. Each variant will run the command.
+//
+// Use a java_genrule instead of a genrule when it needs to depend on or be depended on by other java modules, unless
+// the dependency is for a generated source file.
+//
+// Examples:
+//
+// Use a java_genrule to package generated java resources:
+//
+// java_genrule {
+// name: "generated_resources",
+// tools: [
+// "generator",
+// "soong_zip",
+// ],
+// srcs: ["generator_inputs/**/*"],
+// out: ["generated_android_icu4j_resources.jar"],
+// cmd: "$(location generator) $(in) -o $(genDir) " +
+// "&& $(location soong_zip) -o $(out) -C $(genDir)/res -D $(genDir)/res",
+// }
+//
+// java_library {
+// name: "lib_with_generated_resources",
+// srcs: ["src/**/*.java"],
+// static_libs: ["generated_resources"],
+// }
func genRuleFactory() android.Module {
module := genrule.NewGenRule()
@@ -36,8 +65,9 @@
}
// java_genrule_host is a genrule that can depend on other java_* objects.
-// The cmd may be run multiple times, once for each of the different host/device
-// variations.
+//
+// A java_genrule_host has a single variant that will run against the host variant of its dependencies and
+// produce an output that can be used as an input to a host java rule.
func genRuleFactoryHost() android.Module {
module := genrule.NewGenRule()
diff --git a/java/java.go b/java/java.go
index 76b41ca..c0310da 100644
--- a/java/java.go
+++ b/java/java.go
@@ -36,7 +36,7 @@
android.RegisterModuleType("java_defaults", defaultsFactory)
android.RegisterModuleType("java_library", LibraryFactory)
- android.RegisterModuleType("java_library_static", LibraryFactory)
+ android.RegisterModuleType("java_library_static", LibraryStaticFactory)
android.RegisterModuleType("java_library_host", LibraryHostFactory)
android.RegisterModuleType("java_binary", BinaryFactory)
android.RegisterModuleType("java_binary_host", BinaryHostFactory)
@@ -1450,6 +1450,17 @@
j.deps(ctx)
}
+// java_library builds and links sources into a `.jar` file for the device, and possibly for the host as well.
+//
+// By default, a java_library has a single variant that produces a `.jar` file containing `.class` files that were
+// compiled against the device bootclasspath. This jar is not suitable for installing on a device, but can be used
+// as a `static_libs` dependency of another module.
+//
+// Specifying `installable: true` will product a `.jar` file containing `classes.dex` files, suitable for installing on
+// a device.
+//
+// Specifying `host_supported: true` will produce two variants, one compiled against the device bootclasspath and one
+// compiled against the host bootclasspath.
func LibraryFactory() android.Module {
module := &Library{}
@@ -1463,6 +1474,15 @@
return module
}
+// java_library_static is an obsolete alias for java_library.
+func LibraryStaticFactory() android.Module {
+ return LibraryFactory()
+}
+
+// java_library_host builds and links sources into a `.jar` file for the host.
+//
+// A java_library_host has a single variant that produces a `.jar` file containing `.class` files that were
+// compiled against the host bootclasspath.
func LibraryHostFactory() android.Module {
module := &Library{}
@@ -1521,6 +1541,14 @@
android.ExtractSourcesDeps(ctx, j.testProperties.Data)
}
+// java_test builds a and links sources into a `.jar` file for the device, and possibly for the host as well, and
+// creates an `AndroidTest.xml` file to allow running the test with `atest` or a `TEST_MAPPING` file.
+//
+// By default, a java_test has a single variant that produces a `.jar` file containing `classes.dex` files that were
+// compiled against the device bootclasspath.
+//
+// Specifying `host_supported: true` will produce two variants, one compiled against the device bootclasspath and one
+// compiled against the host bootclasspath.
func TestFactory() android.Module {
module := &Test{}
@@ -1538,6 +1566,11 @@
return module
}
+// java_test_host builds a and links sources into a `.jar` file for the host, and creates an `AndroidTest.xml` file to
+// allow running the test with `atest` or a `TEST_MAPPING` file.
+//
+// A java_test_host has a single variant that produces a `.jar` file containing `.class` files that were
+// compiled against the host bootclasspath.
func TestHostFactory() android.Module {
module := &Test{}
@@ -1619,6 +1652,14 @@
}
}
+// java_binary builds a `.jar` file and a shell script that executes it for the device, and possibly for the host
+// as well.
+//
+// By default, a java_binary has a single variant that produces a `.jar` file containing `classes.dex` files that were
+// compiled against the device bootclasspath.
+//
+// Specifying `host_supported: true` will produce two variants, one compiled against the device bootclasspath and one
+// compiled against the host bootclasspath.
func BinaryFactory() android.Module {
module := &Binary{}
@@ -1636,6 +1677,10 @@
return module
}
+// java_binary_host builds a `.jar` file and a shell script that executes it for the host.
+//
+// A java_binary_host has a single variant that produces a `.jar` file containing `.class` files that were
+// compiled against the host bootclasspath.
func BinaryHostFactory() android.Module {
module := &Binary{}
@@ -1817,6 +1862,13 @@
var _ android.PrebuiltInterface = (*Import)(nil)
+// java_import imports one or more `.jar` files into the build graph as if they were built by a java_library module.
+//
+// By default, a java_import has a single variant that expects a `.jar` file containing `.class` files that were
+// compiled against an Android classpath.
+//
+// Specifying `host_supported: true` will produce two variants, one for use as a dependency of device modules and one
+// for host modules.
func ImportFactory() android.Module {
module := &Import{}
@@ -1827,6 +1879,11 @@
return module
}
+// java_import imports one or more `.jar` files into the build graph as if they were built by a java_library_host
+// module.
+//
+// A java_import_host has a single variant that expects a `.jar` file containing `.class` files that were
+// compiled against a host bootclasspath.
func ImportFactoryHost() android.Module {
module := &Import{}
@@ -1848,6 +1905,37 @@
func (*Defaults) GenerateAndroidBuildActions(ctx android.ModuleContext) {
}
+// java_defaults provides a set of properties that can be inherited by other java or android modules.
+//
+// A module can use the properties from a java_defaults module using `defaults: ["defaults_module_name"]`. Each
+// property in the defaults module that exists in the depending module will be prepended to the depending module's
+// value for that property.
+//
+// Example:
+//
+// java_defaults {
+// name: "example_defaults",
+// srcs: ["common/**/*.java"],
+// javacflags: ["-Xlint:all"],
+// aaptflags: ["--auto-add-overlay"],
+// }
+//
+// java_library {
+// name: "example",
+// defaults: ["example_defaults"],
+// srcs: ["example/**/*.java"],
+// }
+//
+// is functionally identical to:
+//
+// java_library {
+// name: "example",
+// srcs: [
+// "common/**/*.java",
+// "example/**/*.java",
+// ],
+// javacflags: ["-Xlint:all"],
+// }
func defaultsFactory() android.Module {
return DefaultsFactory()
}
