diff --git a/tools/check-flagged-apis/check-flagged-apis.sh b/tools/check-flagged-apis/check-flagged-apis.sh index d9934a11fe..8078cd80bf 100755 --- a/tools/check-flagged-apis/check-flagged-apis.sh +++ b/tools/check-flagged-apis/check-flagged-apis.sh @@ -14,8 +14,13 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Run check-flagged-apis for public APIs and the three @SystemApi flavours -# Usage: lunch && source +# Run check-flagged-apis for public APIs and the three @SystemApi flavours. +# +# This script expects an argument to tell it which subcommand of +# check-flagged-apis to execute. Run the script without any arguments to see +# the valid options. +# +# Remember to lunch to select the relevant release config before running this script. source $(cd $(dirname $BASH_SOURCE) &> /dev/null && pwd)/../../shell_utils.sh require_top @@ -43,6 +48,10 @@ function build() { $MODULE_LIB_XML_VERSIONS } +function noop() { + true +} + function aninja() { local T="$(gettop)" (\cd "${T}" && prebuilts/build-tools/linux-x86/bin/ninja -f out/combined-${TARGET_PRODUCT}.ninja "$@") @@ -52,11 +61,11 @@ function path_to_api_signature_file { aninja -t query device_"$1"_all_targets | grep -A1 -e input: | tail -n1 } -function run() { +function run_check() { local errors=0 echo "# current" - check-flagged-apis \ + check-flagged-apis check \ --api-signature $(path_to_api_signature_file "frameworks-base-api-current.txt") \ --flag-values $(gettop)/out/soong/.intermediates/all_aconfig_declarations.pb \ --api-versions $PUBLIC_XML_VERSIONS @@ -64,7 +73,7 @@ function run() { echo echo "# system-current" - check-flagged-apis \ + check-flagged-apis check \ --api-signature $(path_to_api_signature_file "frameworks-base-api-system-current.txt") \ --flag-values $(gettop)/out/soong/.intermediates/all_aconfig_declarations.pb \ --api-versions $SYSTEM_XML_VERSIONS @@ -72,7 +81,7 @@ function run() { echo echo "# system-server-current" - check-flagged-apis \ + check-flagged-apis check \ --api-signature $(path_to_api_signature_file "frameworks-base-api-system-server-current.txt") \ --flag-values $(gettop)/out/soong/.intermediates/all_aconfig_declarations.pb \ --api-versions $SYSTEM_SERVER_XML_VERSONS @@ -80,7 +89,7 @@ function run() { echo echo "# module-lib" - check-flagged-apis \ + check-flagged-apis check \ --api-signature $(path_to_api_signature_file "frameworks-base-api-module-lib-current.txt") \ --flag-values $(gettop)/out/soong/.intermediates/all_aconfig_declarations.pb \ --api-versions $MODULE_LIB_XML_VERSIONS @@ -89,8 +98,39 @@ function run() { return $errors } -if [[ "$1" != "--skip-build" ]]; then - build && run -else - run +function run_list() { + echo "# current" + check-flagged-apis list \ + --api-signature $(path_to_api_signature_file "frameworks-base-api-current.txt") \ + --flag-values $(gettop)/out/soong/.intermediates/all_aconfig_declarations.pb + + echo + echo "# system-current" + check-flagged-apis list \ + --api-signature $(path_to_api_signature_file "frameworks-base-api-system-current.txt") \ + --flag-values $(gettop)/out/soong/.intermediates/all_aconfig_declarations.pb + + echo + echo "# system-server-current" + check-flagged-apis list \ + --api-signature $(path_to_api_signature_file "frameworks-base-api-system-server-current.txt") \ + --flag-values $(gettop)/out/soong/.intermediates/all_aconfig_declarations.pb + + echo + echo "# module-lib" + check-flagged-apis list \ + --api-signature $(path_to_api_signature_file "frameworks-base-api-module-lib-current.txt") \ + --flag-values $(gettop)/out/soong/.intermediates/all_aconfig_declarations.pb +} + +build_cmd=build +if [[ "$1" == "--skip-build" ]]; then + build_cmd=noop + shift 1 fi + +case "$1" in + check) $build_cmd && run_check ;; + list) $build_cmd && run_list ;; + *) echo "usage: $(basename $0): [--skip-build] check|list"; exit 1 +esac diff --git a/tools/check-flagged-apis/src/com/android/checkflaggedapis/CheckFlaggedApisTest.kt b/tools/check-flagged-apis/src/com/android/checkflaggedapis/CheckFlaggedApisTest.kt index 8e285f6216..e07ac1dfd4 100644 --- a/tools/check-flagged-apis/src/com/android/checkflaggedapis/CheckFlaggedApisTest.kt +++ b/tools/check-flagged-apis/src/com/android/checkflaggedapis/CheckFlaggedApisTest.kt @@ -358,4 +358,23 @@ class CheckFlaggedApisTest { parseApiVersions(API_VERSIONS.byteInputStream())) assertEquals(expected, actual) } + + @Test + fun testListFlaggedApis() { + val expected = + listOf( + "android.flag.bar DISABLED android/Clazz/Builder", + "android.flag.foo ENABLED android/Clazz", + "android.flag.foo ENABLED android/Clazz/Clazz()", + "android.flag.foo ENABLED android/Clazz/FOO", + "android.flag.foo ENABLED android/Clazz/getErrorCode()", + "android.flag.foo ENABLED android/Clazz/innerClassArg(Landroid/Clazz/Builder;)", + "android.flag.foo ENABLED android/Clazz/setData(I[[ILandroid/util/Utility;)", + "android.flag.foo ENABLED android/Clazz/setVariableData(I[Landroid/util/Atom;)") + val actual = + listFlaggedApis( + parseApiSignature("in-memory", API_SIGNATURE.byteInputStream()), + parseFlagValues(generateFlagsProto(ENABLED, DISABLED))) + assertEquals(expected, actual) + } } diff --git a/tools/check-flagged-apis/src/com/android/checkflaggedapis/Main.kt b/tools/check-flagged-apis/src/com/android/checkflaggedapis/Main.kt index 1d2440dee8..1125d393bf 100644 --- a/tools/check-flagged-apis/src/com/android/checkflaggedapis/Main.kt +++ b/tools/check-flagged-apis/src/com/android/checkflaggedapis/Main.kt @@ -26,6 +26,7 @@ import com.android.tools.metalava.model.MethodItem import com.android.tools.metalava.model.text.ApiFile import com.github.ajalt.clikt.core.CliktCommand import com.github.ajalt.clikt.core.ProgramResult +import com.github.ajalt.clikt.core.subcommands import com.github.ajalt.clikt.parameters.options.help import com.github.ajalt.clikt.parameters.options.option import com.github.ajalt.clikt.parameters.options.required @@ -141,6 +142,33 @@ internal data class UnknownFlagError(override val symbol: Symbol, override val f } } +val ARG_API_SIGNATURE = "--api-signature" +val ARG_API_SIGNATURE_HELP = + """ +Path to API signature file. +Usually named *current.txt. +Tip: `m frameworks-base-api-current.txt` will generate a file that includes all platform and mainline APIs. +""" + +val ARG_FLAG_VALUES = "--flag-values" +val ARG_FLAG_VALUES_HELP = + """ +Path to aconfig parsed_flags binary proto file. +Tip: `m all_aconfig_declarations` will generate a file that includes all information about all flags. +""" + +val ARG_API_VERSIONS = "--api-versions" +val ARG_API_VERSIONS_HELP = + """ +Path to API versions XML file. +Usually named xml-versions.xml. +Tip: `m sdk dist` will generate a file that includes all platform and mainline APIs. +""" + +class MainCommand : CliktCommand() { + override fun run() {} +} + class CheckCommand : CliktCommand( help = @@ -152,32 +180,18 @@ This tool reads the API signature file and checks that all flagged APIs are used The tool will exit with a non-zero exit code if any flagged APIs are found to be used in the incorrect way. """) { private val apiSignaturePath by - option("--api-signature") - .help( - """ - Path to API signature file. - Usually named *current.txt. - Tip: `m frameworks-base-api-current.txt` will generate a file that includes all platform and mainline APIs. - """) + option(ARG_API_SIGNATURE) + .help(ARG_API_SIGNATURE_HELP) .path(mustExist = true, canBeDir = false, mustBeReadable = true) .required() private val flagValuesPath by - option("--flag-values") - .help( - """ - Path to aconfig parsed_flags binary proto file. - Tip: `m all_aconfig_declarations` will generate a file that includes all information about all flags. - """) + option(ARG_FLAG_VALUES) + .help(ARG_FLAG_VALUES_HELP) .path(mustExist = true, canBeDir = false, mustBeReadable = true) .required() private val apiVersionsPath by - option("--api-versions") - .help( - """ - Path to API versions XML file. - Usually named xml-versions.xml. - Tip: `m sdk dist` will generate a file that includes all platform and mainline APIs. - """) + option(ARG_API_VERSIONS) + .help(ARG_API_VERSIONS_HELP) .path(mustExist = true, canBeDir = false, mustBeReadable = true) .required() @@ -196,6 +210,40 @@ The tool will exit with a non-zero exit code if any flagged APIs are found to be } } +class ListCommand : + CliktCommand( + help = + """ +List all flagged APIs and corresponding flags. + +The output format is " ", one line per API. + +The output can be post-processed by e.g. piping it to grep to filter out only enabled APIs, or all APIs guarded by a given flag. +""") { + private val apiSignaturePath by + option(ARG_API_SIGNATURE) + .help(ARG_API_SIGNATURE_HELP) + .path(mustExist = true, canBeDir = false, mustBeReadable = true) + .required() + private val flagValuesPath by + option(ARG_FLAG_VALUES) + .help(ARG_FLAG_VALUES_HELP) + .path(mustExist = true, canBeDir = false, mustBeReadable = true) + .required() + + override fun run() { + val flaggedSymbols = + apiSignaturePath.toFile().inputStream().use { + parseApiSignature(apiSignaturePath.toString(), it) + } + val flags = flagValuesPath.toFile().inputStream().use { parseFlagValues(it) } + val output = listFlaggedApis(flaggedSymbols, flags) + if (output.isNotEmpty()) { + println(output.joinToString("\n")) + } + } +} + internal fun parseApiSignature(path: String, input: InputStream): Set> { val output = mutableSetOf>() val visitor = @@ -446,4 +494,35 @@ internal fun findErrors( return errors } -fun main(args: Array) = CheckCommand().main(args) +/** + * Collect all known info about all @FlaggedApi annotated APIs. + * + * Each API will be represented as a String, on the format + * 
+ *   <fully-qualified-name-of-flag< <state-of-flag< <API<
+ *
+ * + * @param flaggedSymbolsInSource the set of symbols that are flagged in the source code + * @param flags the set of flags and their values + * @return a list of Strings encoding API data using the format described above, sorted + * alphabetically + */ +internal fun listFlaggedApis( + flaggedSymbolsInSource: Set>, + flags: Map +): List { + val output = mutableListOf() + for ((symbol, flag) in flaggedSymbolsInSource) { + val flagState = + when (flags.get(flag)) { + true -> "ENABLED" + false -> "DISABLED" + null -> "UNKNOWN" + } + output.add("$flag $flagState ${symbol.toPrettyString()}") + } + output.sort() + return output +} + +fun main(args: Array) = MainCommand().subcommands(CheckCommand(), ListCommand()).main(args)