Update plugin tool documentation and remove unused commands (#8411)

This removes the commands that respond to `bin/plugin make` and
`bin/plugin run`.

Author: helin24

tool/plugin/README.md

@@ -1,116 +1,56 @@
-
 # Flutter Plugin Maintenance Tool
 
-The previous builder for the Flutter plugin was written in Ant. An expert in Ant would probably have no trouble maintaining it, but we have no such expert available. In order to increase stability and productivity we transformed the builder into a Dart command line tool, inspired by the Flutter tool. The tool is named `plugin`, since it helps with plugin development.
-
+The previous builder for the Flutter plugin was written in Ant. An expert in Ant would probably have no trouble maintaining it, but we have
+no such expert available. In order to increase stability and productivity we transformed the builder into a Dart command line tool, inspired
+by the Flutter tool. The tool is named `plugin`, since it helps with plugin development.
 
 ## Functions
 
-The tool needs to perform several functions. Building is the basic one, but others are important too. Implementation note: these will be implemented as compound commands in the CLI tool (similar to `flutter doctor` or `flutter run` in the Flutter CLI tool).
+The tool needs to perform several functions. Building is the basic one, but others are important too. Implementation note: these will be
+implemented as compound commands in the CLI tool (similar to `flutter doctor` or `flutter run` in the Flutter CLI tool).
 
-*   `make`
-*   `test`
-*   `deploy`
-*   `generate`
-*   `lint`
+* `deploy`
+* `generate`
+* `lint`
 
 Each command has its own set of optional arguments. If the CLI tool is invoked without a command then it will print its help message.
 
 There are two global options. On the command line these are given prior to the command name.
 
-
-
-*   `-r, --release=XX`
-Use "release mode." The `XX` value specifies the release identifier, like 18 or 19.1. It will be shown in the "version" field of the plugin manager's listing for the Flutter plugin. In this mode additional constraints must be satisfied. The current git branch must have no unsaved changes and must be named "release_XX". The `.github/workflows/presubmit.yaml` file must be newer than the `product-matrix.json` file (see the `generate` command).
-*   `-d, --cwd=<working-directory>`
-Set the root directory to the `working-directory` value. This should not be used when running the tool from the command line. It is only intended to be used when running tests from IntelliJ run configurations that have no way to specify the working directory.
-
-
-### Make
-
-Builds may be targeted for local development or distribution.
-
-
-
-*   `-[no-]ij`
-Build for IntelliJ. Default is true; may be negated by including `no`.
-*   `-[no-]as`
-Build for Android Studio. Default is true; may be negated by including `no`.
-*   `-o, --only-version=ID`
-Only build the specified IntelliJ version. `ID` is one of the "version" strings in product-matrix.json.
-*   `-u, --unpack`
-Normally the archive files are not unpacked if the corresponding directory exists. This flag forces the archive files to be unpacked.
-
-
-The make function must generate the correct `plugin.xml` for each platform and generate the correct artifacts for each. In release mode the archive files are always unpacked (--unpack is implied). The plugin files are saved in the `artifacts` directory. In release mode a subdirectory of `artifacts` is created which has the name of the release and they are put there. During a local dev/test run the subdirectory is not created and the created files are children of `artifacts`.
-
-Returns a success or failure code to play nice with shell commands.
-
-
-### Test
-
-Both unit and integration tests need to run, and tests should work whether running locally or on Travis.
-
-
-
-*   `-u, --[no-]unit
-`Run unit tests (or not).
-*   `-i, --[no-]integration`
-Run GUI-based integration tests (or not).
-
-TBD: We may need some mechanism to automatically upload testing artifacts, since we can no longer attach zip files to email. This could also potentially be addressed by creating a 'dev' channel for the plugin on the JetBrains store, and publishing to it when we have release candidates.
-
+* `-r, --release=XX`
+  Use "release mode." The `XX` value specifies the release identifier, like 18 or 19.1. It will be shown in the "version" field of the
+  plugin manager's listing for the Flutter plugin. In this mode additional constraints must be satisfied. The current git branch must have
+  no unsaved changes and must be named "release_XX". The `.github/workflows/presubmit.yaml` file must be newer than the
+  `product-matrix.json` file (see the `generate` command).
+* `-d, --cwd=<working-directory>`
+  Set the root directory to the `working-directory` value. This should not be used when running the tool from the command line. It is only
+  intended to be used when running tests from IntelliJ run configurations that have no way to specify the working directory.
 
 ### Deploy
 
-Automatically upload all required artifacts to the JetBrains site. This function will print instructions to retrieve the password from valentine then prompt for the password to log into the JetBrains site. It has no options. Returns a success or failure code to play nice with shell commands.
+Automatically upload all required artifacts to the JetBrains site. This function will print instructions to retrieve the password from
+valentine then prompt for the password to log into the JetBrains site. It has no options. Returns a success or failure code to play nice
+with shell commands.
 (Used primarily by the dev channel Kokoro job. Not sure if it works for uploading to the stable channel.)
 
 ### Generate
 
-Generate a `plugin.xml` from `plugin.xml.template` to be used for launching a runtime workbench. This is different from the ones generated during building because it will have a version range that allows use in all targeted platforms.
-
+This is now only used for live templates (see `resources/liveTemplates`).
 
 ### Lint
 
 Run the lint tool. It checks for bad imports and prints a report of the Dart plugin API usage.
 
-
-## Examples
-
-Build the Flutter plugin for IntelliJ and Android Studio, in distribution mode.
-
-	`plugin -r19.2 make`
-
-Build a local version of the IntelliJ version of the plugin, not for distribution.
-
-	`plugin make --no-as`
-
-Run integration tests without doing a build, assuming an edit-build-test cycle during development.
-
-	`plugin test --no-unit`
-
-Build everything then run all tests. The big question here is: Can we get integration tests to run using the newly-built plugin rather than sources?
-
-	`plugin make && plugin test`
-
 ## Debugging
 
-It can be difficult to debug issues that only occur with a deployable
-plugin built by `plugin make`. Here's how to set up remote
-debugging with IntelliJ:
+It can be difficult to debug issues that only occur with a deployable plugin. Here's how to set up remote debugging with IntelliJ:
 
-In IntelliJ create a "Remote" type of run configuration. It 
-shows you the command-line arg you need to add in the top 
-text field of the run config. Copy that text.
+In IntelliJ create a "Remote" type of run configuration. It shows you the command-line arg you need to add in the top text field of the run
+config. Copy that text.
 
-Now, (assuming you are on a Mac) find your IJ or AS app in 
-the Finder. Right-click, 'Show Package Contents', open 
-Contents, edit Info.plist. In the plist editor expand 
-JVMOptions and then edit VMOptions. Append the copied text 
-to the end. Save the plist editor and launch the AS or IJ app.
+Now, (assuming you are on a Mac) find your IJ or AS app in the Finder. Right-click, 'Show Package Contents', open Contents, edit Info.plist.
+In the plist editor expand JVMOptions and then edit VMOptions. Append the copied text to the end. Save the plist editor and launch the AS or
+IJ app.
 
-Back in IntelliJ, select your new run config and click the 
-debug icon to attach the debugger to the app. The copied 
-text includes "suspend=n". If you want to set a breakpoint 
-before execution begins change that 'n' to 'y'.
+Back in IntelliJ, select your new run config and click the debug icon to attach the debugger to the app. The copied text includes "
+suspend=n". If you want to set a breakpoint before execution begins change that 'n' to 'y'.

tool/plugin/lib/plugin.dart

@@ -21,11 +21,9 @@ Future<int> main(List<String> args) async {
   var runner = BuildCommandRunner();
 
   runner.addCommand(LintCommand(runner));
-  runner.addCommand(GradleBuildCommand(runner));
   runner.addCommand(TestCommand(runner));
   runner.addCommand(DeployCommand(runner));
   runner.addCommand(GenerateCommand(runner));
-  runner.addCommand(RunIdeCommand(runner));
 
   try {
     return await runner.run(args) ?? 0;
@@ -201,170 +199,6 @@ void _copyResources(Directory from, Directory to) {
   }
 }
 
-/// Build deployable plugin files. If the --release argument is given
-/// then perform additional checks to verify that the release environment
-/// is in good order.
-class GradleBuildCommand extends ProductCommand {
-  @override
-  final BuildCommandRunner runner;
-
-  GradleBuildCommand(this.runner) : super('make') {
-    argParser.addOption(
-      'only-version',
-      abbr: 'o',
-      help: 'Only build the specified IntelliJ version; useful for sharding '
-          'builds on CI systems.',
-    );
-    argParser.addFlag(
-      'unpack',
-      abbr: 'u',
-      help: 'Unpack the artifact files during provisioning, '
-          'even if the cache appears fresh.\n'
-          'This flag is ignored if --release is given.',
-      defaultsTo: false,
-    );
-    argParser.addOption(
-      'minor',
-      abbr: 'm',
-      help: 'Set the minor version number.',
-    );
-    argParser.addFlag('setup', abbr: 's', defaultsTo: true);
-  }
-
-  @override
-  String get description => 'Build a deployable version of the Flutter plugin, '
-      'compiled against the specified artifacts.';
-
-  @override
-  Future<int> doit() async {
-    final argResults = this.argResults!;
-    if (isReleaseMode) {
-      if (argResults.flag('unpack')) {
-        separator('Release mode (--release) implies --unpack');
-      }
-      if (!await performReleaseChecks(this)) {
-        return 1;
-      }
-    }
-
-    // Check to see if we should only be building a specific version.
-    final onlyVersion = argResults.option('only-version');
-
-    var buildSpecs = specs;
-    if (onlyVersion != null && onlyVersion.isNotEmpty) {
-      buildSpecs = specs.where((spec) => spec.version == onlyVersion).toList();
-      if (buildSpecs.isEmpty) {
-        log("No spec found for version '$onlyVersion'");
-        return 1;
-      }
-    }
-
-    final minorNumber = argResults.option('minor');
-    if (minorNumber != null) {
-      pluginCount = int.parse(minorNumber) - 1;
-    }
-
-    var result = 0;
-    for (var spec in buildSpecs) {
-      if (spec.channel != channel) {
-        continue;
-      }
-      if (!(isForIntelliJ && isForAndroidStudio)) {
-        // This is a little more complicated than I'd like because the default
-        // is to always do both.
-        if (isForAndroidStudio && !spec.isAndroidStudio) continue;
-        if (isForIntelliJ && spec.isAndroidStudio) continue;
-      }
-
-      pluginCount++;
-      if (spec.isDevChannel && !isDevChannel) {
-        spec.buildForMaster();
-      }
-
-      separator('Building flutter-intellij.jar');
-      await removeAll('build');
-
-      log('$spec');
-
-      result = await applyEdits(spec, () async {
-        return await externalBuildCommand(spec);
-      });
-      if (result != 0) {
-        log('applyEdits() returned ${result.toString()}');
-        return result;
-      }
-
-      try {
-        result = await savePluginArtifact(spec);
-        if (result != 0) {
-          return result;
-        }
-      } catch (ex) {
-        log("$ex");
-        return 1;
-      }
-
-      separator('Built artifact');
-      final releaseFilePath = releasesFilePath(spec);
-      final file = File(releaseFilePath);
-      final fileSize = file.lengthSync() / 1000000;
-      log('$releaseFilePath, $fileSize MB');
-    }
-    if (argResults.option('only-version') == null) {
-      checkAndClearAppliedEditCommands();
-    }
-    // Print a summary of the collection of plugin versions built:
-    var builtVersions = buildSpecs.map((spec) => spec.name).toList().join(', ');
-    log(
-      '\nMake of the ${buildSpecs.length} builds was '
-      'successful: $builtVersions.',
-    );
-    return result;
-  }
-
-  Future<int> externalBuildCommand(BuildSpec spec) async {
-    var pluginFile = File('resources/META-INF/plugin.xml');
-    var studioFile = File('resources/META-INF/studio-contribs.xml');
-    var pluginSrc = pluginFile.readAsStringSync();
-    var studioSrc = studioFile.readAsStringSync();
-    try {
-      return await runner.buildPlugin(spec, buildVersionNumber(spec));
-    } finally {
-      pluginFile.writeAsStringSync(pluginSrc);
-      studioFile.writeAsStringSync(studioSrc);
-    }
-  }
-
-  Future<int> savePluginArtifact(BuildSpec spec) async {
-    final file = File(releasesFilePath(spec));
-
-    // Log the contents of ./build/distributions, this is useful in debugging
-    // in general and especially useful for the Kokoro bot which is run remotely
-    final result = Process.runSync('ls', [
-      '-laf',
-      '-laf',
-      'build/distributions',
-    ]);
-    log('Content generated in ./build/distributions:\n${result.stdout}');
-
-    var source = File('build/distributions/flutter-intellij.zip');
-    if (!source.existsSync()) {
-      source = File('build/distributions/flutter-intellij-kokoro.zip');
-    }
-    _copyFile(source, file.parent, filename: p.basename(file.path));
-    await _stopDaemon();
-    return 0;
-  }
-
-  Future<int> _stopDaemon() async {
-    if (Platform.isWindows) {
-      return await exec('.\\gradlew.bat', ['--stop']);
-    } else {
-      return await exec('./gradlew', ['--stop']);
-    }
-  }
-}
-
 /// Either the --release or --channel options must be provided.
 /// The permanent token is read from the file specified by Kokoro.
 /// This is used by Kokoro to build and upload the dev version of the plugin.
@@ -516,42 +350,6 @@ class GenerateCommand extends ProductCommand {
   }
 }
 
-/// Run the IDE using the gradle task "runIde"
-class RunIdeCommand extends ProductCommand {
-  @override
-  final BuildCommandRunner runner;
-
-  RunIdeCommand(this.runner) : super('run');
-
-  @override
-  String get description => 'Run the IDE plugin';
-
-  @override
-  Future<int> doit() async {
-    final javaHome = Platform.environment['JAVA_HOME'];
-    if (javaHome == null) {
-      log('JAVA_HOME environment variable not set - this is needed by Gradle.');
-      return 1;
-    }
-    log('JAVA_HOME=$javaHome');
-
-    // TODO(jwren) The IDE run is determined currently by the isUnitTestTarget
-    //  in the product-matrix.json, while useful, a new field should be added
-    //  into the product-matrix.json instead of re-using this field,
-    //  Or, the run IDE should be passed via the command line (I don't like this
-    //  as much.)
-    final spec = specs.firstWhere((s) => s.isUnitTestTarget);
-    return await _runIde(spec);
-  }
-
-  Future<int> _runIde(BuildSpec spec) async {
-    // run './gradlew runIde'
-    return await applyEdits(spec, () async {
-      return await runner.runGradleCommand(['runIde'], spec, '1', 'false');
-    });
-  }
-}
-
 abstract class ProductCommand extends Command<int> {
   @override
   final String name;