feat(cordova): use native-run by default

native-run is a utility built by Ionic for running native binaries on
iOS and Android devices and simulators/emulators. See the GitHub repo:
https://github.com/ionic-team/native-run

native-run only works for iOS and Android. If a different platform is
used, Cordova is used to run the app.

BREAKING CHANGE: `ionic cordova run/emulate` no longer use Cordova to
deploy apps by default. `cordova run`, which builds and deploys the app,
is no longer used. Instead, `cordova build` is used to build the app and
then it is deployed to devices using `native-run`. The old behavior is
available by specifying `--no-native-run`. When using Cordova to run,
unless you manually forward ports, you will need to also specify
`--address=0.0.0.0` (or any host accessible externally).

Author: imhoffd

packages/ionic/src/commands/cordova/base.ts

@@ -9,6 +9,7 @@ import { input, strong, weak } from '../../lib/color';
 import { Command } from '../../lib/command';
 import { FatalException } from '../../lib/errors';
 import { runCommand } from '../../lib/executor';
+import { pkgManagerArgs } from '../../lib/utils/npm';
 
 export const CORDOVA_COMPILE_OPTIONS: CommandMetadataOption[] = [
   {
@@ -55,7 +56,7 @@ export const CORDOVA_RUN_OPTIONS: ReadonlyArray<CommandMetadataOption> = [
     summary: `Deploy build to a device (use ${input('--list')} to see all)`,
     type: String,
     groups: [MetadataGroup.ADVANCED, 'cordova', 'cordova-cli', 'native-run'],
-    hint: weak('[cordova]'),
+    hint: weak('[cordova/native-run]'),
   },
 ];
 
@@ -134,17 +135,15 @@ export abstract class CordovaCommand extends Command {
       throw new FatalException('Cannot use Cordova outside a project directory.');
     }
 
-    const { pkgManagerArgs } = await import('../../lib/utils/npm');
-
     try {
       await this.env.shell.run('cordova', argList, { fatalOnNotFound, truncateErrorOutput, cwd: this.integration.root, ...options });
     } catch (e) {
       if (e instanceof SubprocessError) {
         if (e.code === ERROR_COMMAND_NOT_FOUND) {
-          const cdvInstallArgs = await pkgManagerArgs(this.env.config.get('npmClient'), { command: 'install', pkg: 'cordova', global: true });
+          const installArgs = await pkgManagerArgs(this.env.config.get('npmClient'), { command: 'install', pkg: 'cordova', global: true });
           throw new FatalException(
             `The Cordova CLI was not found on your PATH. Please install Cordova globally:\n` +
-            `${input(cdvInstallArgs.join(' '))}\n`
+            `${input(installArgs.join(' '))}\n`
           );
         }
 

packages/ionic/src/commands/cordova/run.ts

@@ -1,47 +1,43 @@
-import { Footnote, LOGGER_LEVELS, MetadataGroup, createPrefixedFormatter } from '@ionic/cli-framework';
-import { onBeforeExit, processExit, sleepForever } from '@ionic/utils-process';
-import { ERROR_COMMAND_NOT_FOUND, SubprocessError } from '@ionic/utils-subprocess';
-import * as path from 'path';
+import { Footnote, MetadataGroup } from '@ionic/cli-framework';
+import { onBeforeExit, sleepForever } from '@ionic/utils-process';
 import * as url from 'url';
 
 import { CommandInstanceInfo, CommandLineInputs, CommandLineOptions, CommandMetadata, CommandMetadataOption, CommandPreRun, IShellRunOptions } from '../../definitions';
 import { COMMON_BUILD_COMMAND_OPTIONS, build } from '../../lib/build';
 import { input, strong, weak } from '../../lib/color';
 import { FatalException } from '../../lib/errors';
 import { loadConfigXml } from '../../lib/integrations/cordova/config';
+import { getPackagePath } from '../../lib/integrations/cordova/project';
 import { filterArgumentsForCordova, generateOptionsForCordovaBuild } from '../../lib/integrations/cordova/utils';
+import { SUPPORTED_PLATFORMS, createNativeRunArgs, createNativeRunListArgs, runNativeRun } from '../../lib/native-run';
 import { COMMON_SERVE_COMMAND_OPTIONS, LOCAL_ADDRESSES, serve } from '../../lib/serve';
-import { createDefaultLoggerHandlers } from '../../lib/utils/logger';
-import { pkgManagerArgs } from '../../lib/utils/npm';
+import { createPrefixedWriteStream } from '../../lib/utils/logger';
 
 import { CORDOVA_BUILD_EXAMPLE_COMMANDS, CORDOVA_RUN_OPTIONS, CordovaCommand } from './base';
 
-const CORDOVA_ANDROID_PACKAGE_PATH = 'platforms/android/app/build/outputs/apk/';
-const CORDOVA_IOS_SIMULATOR_PACKAGE_PATH = 'platforms/ios/build/emulator';
-const CORDOVA_IOS_DEVICE_PACKAGE_PATH = 'platforms/ios/build/device';
-
 const NATIVE_RUN_OPTIONS: ReadonlyArray<CommandMetadataOption> = [
   {
     name: 'native-run',
-    summary: `Use ${input('native-run')} instead of Cordova for running the app`,
+    summary: `Do not use ${input('native-run')} to run the app; use Cordova instead`,
     type: Boolean,
-    groups: [MetadataGroup.EXPERIMENTAL, 'native-run'],
+    default: true,
+    groups: ['native-run'],
     hint: weak('[native-run]'),
   },
   {
     name: 'connect',
     summary: 'Do not tie the running app to the process',
     type: Boolean,
     default: true,
-    groups: [MetadataGroup.EXPERIMENTAL, 'native-run'],
-    hint: weak('[native-run]'),
+    groups: ['native-run'],
+    hint: weak('[native-run] (--livereload)'),
   },
   {
     name: 'json',
-    summary: `Output ${input('--list')} targets in JSON`,
+    summary: `Output targets in JSON`,
     type: Boolean,
-    groups: [MetadataGroup.EXPERIMENTAL, 'native-run'],
-    hint: weak('[native-run]'),
+    groups: [MetadataGroup.ADVANCED, 'native-run'],
+    hint: weak('[native-run] (--list)'),
   },
 ];
 
@@ -128,13 +124,15 @@ export class RunCommand extends CordovaCommand implements CommandPreRun {
       type: 'project',
       summary: 'Run an Ionic project on a connected device',
       description: `
-Like running ${input('cordova run')} or ${input('cordova emulate')} directly, but performs ${input('ionic build')} before deploying to the device or emulator. Optionally specify the ${input('--livereload')} option to use the dev server from ${input('ionic serve')} for livereload functionality.
+Build your app and deploy it to devices and emulators using this command. Optionally specify the ${input('--livereload')} option to use the dev server from ${input('ionic serve')} for livereload functionality.
 
-For Android and iOS, you can setup Remote Debugging on your device with browser development tools using these docs[^remote-debugging-docs].
+This command will first use ${input('ionic build')} to build web assets (or ${input('ionic serve')} with the ${input('--livereload')} option). Then, ${input('cordova build')} is used to compile and prepare your app. Finally, the ${input('native-run')} utility[^native-run-repo] is used to run your app on a device. To use Cordova for this process instead, use the ${input('--no-native-run')} option.
+
+If you have multiple devices and emulators, you can target a specific one with the ${input('--target')} option. You can list targets with ${input('--list')}.
 
-Just like with ${input('ionic cordova build')}, you can pass additional options to the Cordova CLI using the ${input('--')} separator. To pass additional options to the dev server, consider using ${input('ionic serve')} and the ${input('--livereload-url')} option.
+For Android and iOS, you can setup Remote Debugging on your device with browser development tools using these docs[^remote-debugging-docs].
 
-With the experimental ${input('--native-run')} flag, this command will first use Cordova to build your app, and then it will run it on a device using the ${input('native-run')} utility[^native-run-repo] instead of Cordova.
+Just like with ${input('ionic cordova build')}, you can pass additional options to the Cordova CLI using the ${input('--')} separator. To pass additional options to the dev server, consider using ${input('ionic serve')} separately and using the ${input('--livereload-url')} option.
       `,
       footnotes,
       exampleCommands,
@@ -181,7 +179,7 @@ With the experimental ${input('--native-run')} flag, this command will first use
 
       if (options['native-run']) {
         const args = createNativeRunListArgs(inputs, options);
-        await this.nativeRun(args);
+        await this.runNativeRun(args);
       } else {
         const args = filterArgumentsForCordova(metadata, options);
         await this.runCordova(['run', ...args.slice(1)], {});
@@ -191,180 +189,113 @@ With the experimental ${input('--native-run')} flag, this command will first use
     }
 
     if (!inputs[0]) {
-      const platform = await this.env.prompt({
+      const p = await this.env.prompt({
         type: 'input',
         name: 'platform',
         message: `What platform would you like to run (${['android', 'ios'].map(v => input(v)).join(', ')}):`,
       });
 
-      inputs[0] = platform.trim();
+      inputs[0] = p.trim();
     }
 
-    await this.checkForPlatformInstallation(inputs[0]);
+    const [ platform ] = inputs;
+
+    if (options['native-run'] && !SUPPORTED_PLATFORMS.includes(platform)) {
+      this.env.log.warn(`${input(platform)} is not supported by ${input('native-run')}. Using Cordova to run the app.`);
+      options['native-run'] = false;
+    }
+
+    await this.checkForPlatformInstallation(platform);
   }
 
   async run(inputs: CommandLineInputs, options: CommandLineOptions): Promise<void> {
+    if (options['livereload']) {
+      await this.runServeDeploy(inputs, options);
+    } else {
+      await this.runBuildDeploy(inputs, options);
+    }
+  }
+
+  async runServeDeploy(inputs: CommandLineInputs, options: CommandLineOptions) {
     if (!this.project) {
       throw new FatalException(`Cannot run ${input('ionic cordova run/emulate')} outside a project directory.`);
     }
 
+    const conf = await loadConfigXml(this.integration);
     const metadata = await this.getMetadata();
 
-    if (options['livereload']) {
-      let livereloadUrl = options['livereload-url'] ? String(options['livereload-url']) : undefined;
-
-      if (!livereloadUrl) {
-        // TODO: use runner directly
-        const details = await serve({ flags: this.env.flags, config: this.env.config, log: this.env.log, prompt: this.env.prompt, shell: this.env.shell, project: this.project }, inputs, generateOptionsForCordovaBuild(metadata, inputs, options));
+    let livereloadUrl = options['livereload-url'] ? String(options['livereload-url']) : undefined;
 
-        if (details.externallyAccessible === false && !options['native-run']) {
-          const extra = LOCAL_ADDRESSES.includes(details.externalAddress) ? '\nEnsure you have proper port forwarding setup from your device to your computer.' : '';
-          this.env.log.warn(`Your device or emulator may not be able to access ${strong(details.externalAddress)}.${extra}\n\n`);
-        }
+    if (!livereloadUrl) {
+      // TODO: use runner directly
+      const details = await serve({ flags: this.env.flags, config: this.env.config, log: this.env.log, prompt: this.env.prompt, shell: this.env.shell, project: this.project }, inputs, generateOptionsForCordovaBuild(metadata, inputs, options));
 
-        livereloadUrl = `${details.protocol || 'http'}://${options['native-run'] ? details.localAddress : details.externalAddress}:${details.port}`;
+      if (details.externallyAccessible === false && !options['native-run']) {
+        const extra = LOCAL_ADDRESSES.includes(details.externalAddress) ? '\nEnsure you have proper port forwarding setup from your device to your computer.' : '';
+        this.env.log.warn(`Your device or emulator may not be able to access ${strong(details.externalAddress)}.${extra}\n\n`);
       }
 
-      const conf = await loadConfigXml(this.integration);
-
-      onBeforeExit(async () => {
-        conf.resetContentSrc();
-        await conf.save();
-      });
+      livereloadUrl = `${details.protocol || 'http'}://${options['native-run'] ? details.localAddress : details.externalAddress}:${details.port}`;
+    }
 
-      conf.writeContentSrc(livereloadUrl);
+    onBeforeExit(async () => {
+      conf.resetContentSrc();
       await conf.save();
+    });
 
-      const cordovalog = this.env.log.clone();
-      cordovalog.handlers = createDefaultLoggerHandlers(createPrefixedFormatter(`${weak(`[cordova]`)} `));
-      const cordovalogws = cordovalog.createWriteStream(LOGGER_LEVELS.INFO);
+    conf.writeContentSrc(livereloadUrl);
+    await conf.save();
 
-      if (options['native-run']) {
-        // hack to do just Cordova build instead
-        metadata.name = 'build';
+    const cordovalogws = createPrefixedWriteStream(this.env.log, weak(`[cordova]`));
 
-        const buildOpts: IShellRunOptions = { stream: cordovalogws };
-        // ignore very verbose compiler output unless --verbose (still pipe stderr)
-        if (!options['verbose']) {
-          buildOpts.stdio = ['ignore', 'ignore', 'pipe'];
-        }
-        await this.runCordova(filterArgumentsForCordova(metadata, options), buildOpts);
+    if (options['native-run']) {
+      const [ platform ] = inputs;
+      const packagePath = await getPackagePath(conf.getProjectInfo().name, platform, options['emulator'] as boolean);
+      const { port: portForward } = url.parse(livereloadUrl);
 
-        const platform = inputs[0];
-        const packagePath = getPackagePath(conf.getProjectInfo().name, platform, options['emulator'] as boolean);
-        const nativeRunArgs = createNativeRunArgs(packagePath, platform, livereloadUrl, options);
-        await this.nativeRun(nativeRunArgs);
-      } else {
-        await this.runCordova(filterArgumentsForCordova(metadata, options), { stream: cordovalogws });
-        await sleepForever();
-      }
-    } else {
-      if (options.build) {
-        // TODO: use runner directly
-        await build({ config: this.env.config, log: this.env.log, shell: this.env.shell, prompt: this.env.prompt, project: this.project }, inputs, generateOptionsForCordovaBuild(metadata, inputs, options));
+      const buildOpts: IShellRunOptions = { stream: cordovalogws };
+      // ignore very verbose compiler output unless --verbose (still pipe stderr)
+      if (!options['verbose']) {
+        buildOpts.stdio = ['ignore', 'ignore', 'pipe'];
       }
 
-      await this.runCordova(filterArgumentsForCordova(metadata, options));
+      await this.runCordova(filterArgumentsForCordova({ ...metadata, name: 'build' }, options), buildOpts);
+      await this.runNativeRun(createNativeRunArgs({ packagePath, platform, portForward }, options));
+    } else {
+      await this.runCordova(filterArgumentsForCordova(metadata, options), { stream: cordovalogws });
+      await sleepForever();
     }
   }
 
-  protected async nativeRun(args: ReadonlyArray<string>): Promise<void> {
+  async runBuildDeploy(inputs: CommandLineInputs, options: CommandLineOptions) {
     if (!this.project) {
       throw new FatalException(`Cannot run ${input('ionic cordova run/emulate')} outside a project directory.`);
     }
 
-    let ws: NodeJS.WritableStream | undefined;
+    const conf = await loadConfigXml(this.integration);
+    const metadata = await this.getMetadata();
 
-    if (!args.includes('--list')) {
-      const log = this.env.log.clone();
-      log.handlers = createDefaultLoggerHandlers(createPrefixedFormatter(weak(`[native-run]`)));
-      ws = log.createWriteStream(LOGGER_LEVELS.INFO);
+    if (options.build) {
+      // TODO: use runner directly
+      await build({ config: this.env.config, log: this.env.log, shell: this.env.shell, prompt: this.env.prompt, project: this.project }, inputs, generateOptionsForCordovaBuild(metadata, inputs, options));
     }
 
-    try {
-      await this.env.shell.run('native-run', args, { showCommand: !args.includes('--json'), fatalOnNotFound: false, cwd: this.project.directory, stream: ws });
-    } catch (e) {
-      if (e instanceof SubprocessError && e.code === ERROR_COMMAND_NOT_FOUND) {
-        const cdvInstallArgs = await pkgManagerArgs(this.env.config.get('npmClient'), { command: 'install', pkg: 'native-run', global: true });
-        throw new FatalException(
-          `${input('native-run')} was not found on your PATH. Please install it globally:\n` +
-          `${input(cdvInstallArgs.join(' '))}\n`
-        );
-      }
+    if (options['native-run']) {
+      const [ platform ] = inputs;
+      const packagePath = await getPackagePath(conf.getProjectInfo().name, platform, options['emulator'] as boolean);
 
-      throw e;
-    }
-
-    // If we connect the `native-run` process to the running app, then we
-    // should also connect the Ionic CLI with the running `native-run` process.
-    // This will exit the Ionic CLI when `native-run` exits.
-    if (args.includes('--connect')) {
-      processExit(0); // tslint:disable-line:no-floating-promises
+      await this.runCordova(filterArgumentsForCordova({ ...metadata, name: 'build' }, options));
+      await this.runNativeRun(createNativeRunArgs({ packagePath, platform }, { ...options, connect: false }));
+    } else {
+      await this.runCordova(filterArgumentsForCordova(metadata, options));
     }
   }
-}
-
-function createNativeRunArgs(packagePath: string, platform: string, livereloadUrl: string, options: CommandLineOptions): string[] {
-  const opts = [platform, '--app', packagePath];
-  const target = options['target'] ? String(options['target']) : undefined;
-
-  if (target) {
-    opts.push('--target', target);
-  } else if (options['emulator']) {
-    opts.push('--virtual');
-  }
 
-  if (options['connect']) {
-    opts.push('--connect');
-  }
-
-  if (!options['livereload-url']) {
-    const { port } = url.parse(livereloadUrl);
-    opts.push('--forward', `${port}:${port}`);
-  }
-
-  if (options['json']) {
-    opts.push('--json');
-  }
-
-  if (options['verbose']) {
-    opts.push('--verbose');
-  }
-
-  return opts;
-}
-
-function createNativeRunListArgs(inputs: string[], options: CommandLineOptions): string[] {
-  const args = [];
-  if (inputs[0]) {
-    args.push(inputs[0]);
-  }
-  args.push('--list');
-  if (options['json']) {
-    args.push('--json');
-  }
-  if (options['device']) {
-    args.push('--device');
-  }
-  if (options['emulator']) {
-    args.push('--virtual');
-  }
-  if (options['json']) {
-    args.push('--json');
-  }
-
-  return args;
-}
+  protected async runNativeRun(args: ReadonlyArray<string>): Promise<void> {
+    if (!this.project) {
+      throw new FatalException(`Cannot run ${input('ionic cordova run/emulate')} outside a project directory.`);
+    }
 
-function getPackagePath(appName: string, platform: string, emulator: boolean) {
-  if (platform === 'android') {
-    // TODO: don't hardcode this/support multiple build paths (ex: multiple arch builds)
-    // use app/build/outputs/apk/debug/output.json?
-    return path.join(CORDOVA_ANDROID_PACKAGE_PATH, 'debug', 'app-debug.apk');
-  }
-  if (platform === 'ios' && emulator) {
-    return path.join(CORDOVA_IOS_SIMULATOR_PACKAGE_PATH, `${appName}.app`);
-  } else {
-    return path.join(CORDOVA_IOS_DEVICE_PACKAGE_PATH, `${appName}.ipa`);
+    await runNativeRun(this.env, args, { cwd: this.project.directory });
   }
 }