blob: e1af42fd7245c4740dfa83c275dfd9b82974c5e4 [file] [log] [blame]
// Copyright 2013 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
import 'package:file/file.dart';
import 'package:meta/meta.dart';
import 'package:pub_semver/pub_semver.dart';
import 'common/core.dart';
import 'common/output_utils.dart';
import 'common/package_looping_command.dart';
import 'common/plugin_utils.dart';
import 'common/repository_package.dart';
/// The lowest `ext.kotlin_version` that example apps are allowed to use.
@visibleForTesting
final Version minKotlinVersion = Version(1, 7, 10);
/// A command to enforce gradle file conventions and best practices.
class GradleCheckCommand extends PackageLoopingCommand {
/// Creates an instance of the gradle check command.
GradleCheckCommand(super.packagesDir);
@override
final String name = 'gradle-check';
@override
List<String> get aliases => <String>['check-gradle'];
@override
final String description =
'Checks that gradle files follow repository conventions.';
@override
bool get hasLongOutput => false;
@override
PackageLoopingType get packageLoopingType =>
PackageLoopingType.includeAllSubpackages;
@override
Future<PackageResult> runForPackage(RepositoryPackage package) async {
if (!package.platformDirectory(FlutterPlatform.android).existsSync()) {
return PackageResult.skip('No android/ directory.');
}
const String exampleDirName = 'example';
final bool isExample = package.directory.basename == exampleDirName ||
package.directory.parent.basename == exampleDirName;
if (!_validateBuildGradles(package, isExample: isExample)) {
return PackageResult.fail();
}
return PackageResult.success();
}
bool _validateBuildGradles(RepositoryPackage package,
{required bool isExample}) {
final Directory androidDir =
package.platformDirectory(FlutterPlatform.android);
final File topLevelGradleFile = _getBuildGradleFile(androidDir);
// This is tracked as a variable rather than a sequence of &&s so that all
// failures are reported at once, not just the first one.
bool succeeded = true;
if (isExample) {
if (!_validateExampleTopLevelBuildGradle(package, topLevelGradleFile)) {
succeeded = false;
}
final File topLevelSettingsGradleFile =
_getSettingsGradleFile(androidDir);
if (!_validateExampleTopLevelSettingsGradle(
package, topLevelSettingsGradleFile)) {
succeeded = false;
}
final File appGradleFile =
_getBuildGradleFile(androidDir.childDirectory('app'));
if (!_validateExampleAppBuildGradle(package, appGradleFile)) {
succeeded = false;
}
} else {
succeeded = _validatePluginBuildGradle(package, topLevelGradleFile);
}
return succeeded;
}
// Returns the gradle file in the given directory.
File _getBuildGradleFile(Directory dir) => dir.childFile('build.gradle');
// Returns the settings gradle file in the given directory.
File _getSettingsGradleFile(Directory dir) =>
dir.childFile('settings.gradle');
// Returns the main/AndroidManifest.xml file for the given package.
File _getMainAndroidManifest(RepositoryPackage package,
{required bool isExample}) {
final Directory androidDir =
package.platformDirectory(FlutterPlatform.android);
final Directory baseDir =
isExample ? androidDir.childDirectory('app') : androidDir;
return baseDir
.childDirectory('src')
.childDirectory('main')
.childFile('AndroidManifest.xml');
}
bool _isCommented(String line) => line.trim().startsWith('//');
/// Validates the build.gradle file for a plugin
/// (some_plugin/android/build.gradle).
bool _validatePluginBuildGradle(RepositoryPackage package, File gradleFile) {
print('${indentation}Validating '
'${getRelativePosixPath(gradleFile, from: package.directory)}.');
final String contents = gradleFile.readAsStringSync();
final List<String> lines = contents.split('\n');
// This is tracked as a variable rather than a sequence of &&s so that all
// failures are reported at once, not just the first one.
bool succeeded = true;
if (!_validateNamespace(package, contents, isExample: false)) {
succeeded = false;
}
if (!_validateCompatibilityVersions(lines)) {
succeeded = false;
}
if (!_validateGradleDrivenLintConfig(package, lines)) {
succeeded = false;
}
return succeeded;
}
/// Documentation url for Artifact hub implementation in flutter repo's.
@visibleForTesting
static const String artifactHubDocumentationString =
r'https://github.com/flutter/flutter/wiki/Plugins-and-Packages-repository-structure#gradle-structure';
/// String printed as example of valid example root build.gradle repository
/// configuration that enables artifact hub env variable.
@visibleForTesting
static const String exampleRootGradleArtifactHubString = '''
// See $artifactHubDocumentationString for more info.
def artifactRepoKey = 'ARTIFACT_HUB_REPOSITORY'
if (System.getenv().containsKey(artifactRepoKey)) {
println "Using artifact hub"
maven { url System.getenv(artifactRepoKey) }
}
''';
/// Validates that [gradleLines] reads and uses a artifiact hub repository
/// when ARTIFACT_HUB_REPOSITORY is set.
///
/// Required in root gradle file.
bool _validateArtifactHubUsage(
RepositoryPackage example, List<String> gradleLines) {
// Gradle variable name used to hold environment variable string.
const String keyVariable = 'artifactRepoKey';
final RegExp keyPresentRegex =
RegExp('$keyVariable' r"\s+=\s+'ARTIFACT_HUB_REPOSITORY'");
final RegExp documentationPresentRegex = RegExp(
r'github\.com.*wiki.*Plugins-and-Packages-repository-structure.*gradle-structure');
final RegExp keyReadRegex =
RegExp(r'if.*System\.getenv.*\.containsKey.*' '$keyVariable');
final RegExp keyUsedRegex =
RegExp(r'maven.*url.*System\.getenv\(' '$keyVariable');
final bool keyPresent =
gradleLines.any((String line) => keyPresentRegex.hasMatch(line));
final bool documentationPresent = gradleLines
.any((String line) => documentationPresentRegex.hasMatch(line));
final bool keyRead =
gradleLines.any((String line) => keyReadRegex.hasMatch(line));
final bool keyUsed =
gradleLines.any((String line) => keyUsedRegex.hasMatch(line));
if (!(documentationPresent && keyPresent && keyRead && keyUsed)) {
printError('Failed Artifact Hub validation. Include the following in '
'example root build.gradle:\n$exampleRootGradleArtifactHubString');
}
return keyPresent && documentationPresent && keyRead && keyUsed;
}
/// Validates the top-level settings.gradle for an example app (e.g.,
/// some_package/example/android/settings.gradle).
bool _validateExampleTopLevelSettingsGradle(
RepositoryPackage package, File gradleSettingsFile) {
print('${indentation}Validating '
'${getRelativePosixPath(gradleSettingsFile, from: package.directory)}.');
final String contents = gradleSettingsFile.readAsStringSync();
final List<String> lines = contents.split('\n');
// This is tracked as a variable rather than a sequence of &&s so that all
// failures are reported at once, not just the first one.
bool succeeded = true;
if (!_validateArtifactHubSettingsUsage(package, lines)) {
succeeded = false;
}
return succeeded;
}
/// String printed as example of valid example root settings.gradle repository
/// configuration that enables artifact hub env variable.
@visibleForTesting
static String exampleRootSettingsArtifactHubString = '''
// See $artifactHubDocumentationString for more info.
buildscript {
repositories {
maven {
url "https://plugins.gradle.org/m2/"
}
}
dependencies {
classpath "gradle.plugin.com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.2.1"
}
}
apply plugin: "com.google.cloud.artifactregistry.gradle-plugin"
''';
/// Validates that [gradleLines] reads and uses a artifiact hub repository
/// when ARTIFACT_HUB_REPOSITORY is set.
///
/// Required in root gradle file.
bool _validateArtifactHubSettingsUsage(
RepositoryPackage example, List<String> gradleLines) {
final RegExp documentationPresentRegex = RegExp(
r'github\.com.*wiki.*Plugins-and-Packages-repository-structure.*gradle-structure');
final RegExp artifactRegistryDefinitionRegex = RegExp(
r'classpath.*gradle\.plugin\.com\.google\.cloud\.artifactregistry:artifactregistry-gradle-plugin');
final RegExp artifactRegistryPluginApplyRegex = RegExp(
r'apply.*plugin.*com\.google\.cloud\.artifactregistry\.gradle-plugin');
final bool documentationPresent = gradleLines
.any((String line) => documentationPresentRegex.hasMatch(line));
final bool artifactRegistryDefined = gradleLines
.any((String line) => artifactRegistryDefinitionRegex.hasMatch(line));
final bool artifactRegistryPluginApplied = gradleLines
.any((String line) => artifactRegistryPluginApplyRegex.hasMatch(line));
if (!(documentationPresent &&
artifactRegistryDefined &&
artifactRegistryPluginApplied)) {
printError('Failed Artifact Hub validation. Include the following in '
'example root settings.gradle:\n$exampleRootSettingsArtifactHubString');
}
return documentationPresent &&
artifactRegistryDefined &&
artifactRegistryPluginApplied;
}
/// Validates the top-level build.gradle for an example app (e.g.,
/// some_package/example/android/build.gradle).
bool _validateExampleTopLevelBuildGradle(
RepositoryPackage package, File gradleFile) {
print('${indentation}Validating '
'${getRelativePosixPath(gradleFile, from: package.directory)}.');
final String contents = gradleFile.readAsStringSync();
final List<String> lines = contents.split('\n');
// This is tracked as a variable rather than a sequence of &&s so that all
// failures are reported at once, not just the first one.
bool succeeded = true;
if (!_validateJavacLintConfig(package, lines)) {
succeeded = false;
}
if (!_validateKotlinVersion(package, lines)) {
succeeded = false;
}
if (!_validateArtifactHubUsage(package, lines)) {
succeeded = false;
}
return succeeded;
}
/// Validates the app-level build.gradle for an example app (e.g.,
/// some_package/example/android/app/build.gradle).
bool _validateExampleAppBuildGradle(
RepositoryPackage package, File gradleFile) {
print('${indentation}Validating '
'${getRelativePosixPath(gradleFile, from: package.directory)}.');
final String contents = gradleFile.readAsStringSync();
// This is tracked as a variable rather than a sequence of &&s so that all
// failures are reported at once, not just the first one.
bool succeeded = true;
if (!_validateNamespace(package, contents, isExample: true)) {
succeeded = false;
}
return succeeded;
}
/// Validates that [gradleContents] sets a namespace, which is required for
/// compatibility with apps that use AGP 8+.
bool _validateNamespace(RepositoryPackage package, String gradleContents,
{required bool isExample}) {
final RegExp namespaceRegex =
RegExp('^\\s*namespace\\s+[\'"](.*?)[\'"]', multiLine: true);
final RegExpMatch? namespaceMatch =
namespaceRegex.firstMatch(gradleContents);
// For plugins, make sure the namespace is conditionalized so that it
// doesn't break client apps using AGP 4.1 and earlier (which don't have
// a namespace property, and will fail to build if it's set).
const String namespaceConditional =
'if (project.android.hasProperty("namespace"))';
String exampleSetNamespace = "namespace 'dev.flutter.foo'";
if (!isExample) {
exampleSetNamespace = '''
$namespaceConditional {
$exampleSetNamespace
}''';
}
// Wrap the namespace command in an `android` block, adding the indentation
// to make it line up correctly.
final String exampleAndroidNamespaceBlock = '''
android {
${exampleSetNamespace.split('\n').join('\n ')}
}
''';
if (namespaceMatch == null) {
final String errorMessage = '''
build.gradle must set a "namespace":
$exampleAndroidNamespaceBlock
The value must match the "package" attribute in AndroidManifest.xml, if one is
present. For more information, see:
https://developer.android.com/build/publish-library/prep-lib-release#choose-namespace
''';
printError(
'$indentation${errorMessage.split('\n').join('\n$indentation')}');
return false;
} else {
if (!isExample && !gradleContents.contains(namespaceConditional)) {
final String errorMessage = '''
build.gradle for a plugin must conditionalize "namespace":
$exampleAndroidNamespaceBlock
''';
printError(
'$indentation${errorMessage.split('\n').join('\n$indentation')}');
return false;
}
return _validateNamespaceMatchesManifest(package,
isExample: isExample, namespace: namespaceMatch.group(1)!);
}
}
/// Validates that the given namespace matches the manifest package of
/// [package] (if any; a package does not need to be in the manifest in cases
/// where compatibility with AGP <7 is no longer required).
///
/// Prints an error and returns false if validation fails.
bool _validateNamespaceMatchesManifest(RepositoryPackage package,
{required bool isExample, required String namespace}) {
final RegExp manifestPackageRegex = RegExp(r'package\s*=\s*"(.*?)"');
final String manifestContents =
_getMainAndroidManifest(package, isExample: isExample)
.readAsStringSync();
final RegExpMatch? packageMatch =
manifestPackageRegex.firstMatch(manifestContents);
if (packageMatch != null && namespace != packageMatch.group(1)) {
final String errorMessage = '''
build.gradle "namespace" must match the "package" attribute in AndroidManifest.xml, if one is present.
build.gradle namespace: "$namespace"
AndroidMastifest.xml package: "${packageMatch.group(1)}"
''';
printError(
'$indentation${errorMessage.split('\n').join('\n$indentation')}');
return false;
}
return true;
}
/// Checks for a source compatibiltiy version, so that it's explicit rather
/// than using whatever the client's local toolchaing defaults to (which can
/// lead to compile errors that show up for clients, but not in CI).
bool _validateCompatibilityVersions(List<String> gradleLines) {
final bool hasLanguageVersion = gradleLines.any((String line) =>
line.contains('languageVersion') && !_isCommented(line));
final bool hasCompabilityVersions = gradleLines.any((String line) =>
line.contains('sourceCompatibility') && !_isCommented(line)) &&
// Newer toolchains default targetCompatibility to the same value as
// sourceCompatibility, but older toolchains require it to be set
// explicitly. The exact version cutoff (and of which piece of the
// toolchain; likely AGP) is unknown; for context see
// https://github.com/flutter/flutter/issues/125482
gradleLines.any((String line) =>
line.contains('targetCompatibility') && !_isCommented(line));
if (!hasLanguageVersion && !hasCompabilityVersions) {
const String errorMessage = '''
build.gradle must set an explicit Java compatibility version.
This can be done either via "sourceCompatibility"/"targetCompatibility":
android {
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
or "toolchain":
java {
toolchain {
languageVersion = JavaLanguageVersion.of(8)
}
}
See:
https://docs.gradle.org/current/userguide/java_plugin.html#toolchain_and_compatibility
for more details.''';
printError(
'$indentation${errorMessage.split('\n').join('\n$indentation')}');
return false;
}
return true;
}
/// Returns whether the given gradle content is configured to enable all
/// Gradle-driven lints (those checked by ./gradlew lint) and treat them as
/// errors.
bool _validateGradleDrivenLintConfig(
RepositoryPackage package, List<String> gradleLines) {
final List<String> gradleBuildContents = package
.platformDirectory(FlutterPlatform.android)
.childFile('build.gradle')
.readAsLinesSync();
if (!gradleBuildContents.any((String line) =>
line.contains('checkAllWarnings true') && !_isCommented(line)) ||
!gradleBuildContents.any((String line) =>
line.contains('warningsAsErrors true') && !_isCommented(line))) {
printError('${indentation}This package is not configured to enable all '
'Gradle-driven lint warnings and treat them as errors. '
'Please add the following to the lintOptions section of '
'android/build.gradle:');
print('''
checkAllWarnings true
warningsAsErrors true
''');
return false;
}
return true;
}
/// Validates whether the given [example]'s gradle content is configured to
/// build its plugin target with javac lints enabled and treated as errors,
/// if the enclosing package is a plugin.
///
/// This can only be called on example packages. (Plugin packages should not
/// be configured this way, since it would affect clients.)
///
/// If [example]'s enclosing package is not a plugin package, this just
/// returns true.
bool _validateJavacLintConfig(
RepositoryPackage example, List<String> gradleLines) {
final RepositoryPackage enclosingPackage = example.getEnclosingPackage()!;
if (!pluginSupportsPlatform(platformAndroid, enclosingPackage,
requiredMode: PlatformSupport.inline)) {
return true;
}
final String enclosingPackageName = enclosingPackage.directory.basename;
// The check here is intentionally somewhat loose, to allow for the
// possibility of variations (e.g., not using Xlint:all in some cases, or
// passing other arguments).
if (!(gradleLines.any((String line) =>
line.contains('project(":$enclosingPackageName")')) &&
gradleLines.any((String line) =>
line.contains('options.compilerArgs') &&
line.contains('-Xlint') &&
line.contains('-Werror')))) {
printError('The example '
'"${getRelativePosixPath(example.directory, from: enclosingPackage.directory)}" '
'is not configured to treat javac lints and warnings as errors. '
'Please add the following to its build.gradle:');
print('''
gradle.projectsEvaluated {
project(":$enclosingPackageName") {
tasks.withType(JavaCompile) {
options.compilerArgs << "-Xlint:all" << "-Werror"
}
}
}
''');
return false;
}
return true;
}
/// Validates whether the given [example] has its Kotlin version set to at
/// least a minimum value, if it is set at all.
bool _validateKotlinVersion(
RepositoryPackage example, List<String> gradleLines) {
final RegExp kotlinVersionRegex =
RegExp(r"ext\.kotlin_version\s*=\s*'([\d.]+)'");
RegExpMatch? match;
if (gradleLines.any((String line) {
match = kotlinVersionRegex.firstMatch(line);
return match != null;
})) {
final Version version = Version.parse(match!.group(1)!);
if (version < minKotlinVersion) {
printError('build.gradle sets "ext.kotlin_version" to "$version". The '
'minimum Kotlin version that can be specified is '
'$minKotlinVersion, for compatibility with modern dependencies.');
return false;
}
}
return true;
}
}