support custom launch arguments (#84)

* add amStartArgs launch property to allow launch command arguments to be customised.

* update readme launch options docs

src/debugMain.js

@@ -53,6 +53,18 @@ class AndroidDebugSession extends DebugSession {
         // the full file path name of the AndroidManifest.xml, taken from the manifestFile launch property
         this.manifest_fpn = '';
 
+        /**
+         * array of custom arguments to pass to `pm install`
+         * @type {string[]}
+         */
+        this.pm_install_args = null;
+
+        /**
+         * array of custom arguments to pass to `am start`
+         * @type {string[]}
+         */
+        this.am_start_args = null;
+
         /**
          * the threads (from the last refreshThreads() call)
          * @type {AndroidThread[]}
@@ -263,10 +275,18 @@ class AndroidDebugSession extends DebugSession {
         this.app_src_root = ensure_path_end_slash(args.appSrcRoot);
         this.apk_fpn = args.apkFile;
         this.manifest_fpn = args.manifestFile;
-        this.pmInstallArgs = args.pmInstallArgs;
+        this.pm_install_args = args.pmInstallArgs;
+        this.am_start_args = args.amStartArgs;
         if (typeof args.callStackDisplaySize === 'number' && args.callStackDisplaySize >= 0)
             this.callStackDisplaySize = args.callStackDisplaySize|0;
 
+        // we don't allow both amStartArgs and launchActivity to be specified (the launch activity must be included in amStartArgs)
+        if (args.amStartArgs && args.launchActivity) {
+            this.LOG('amStartArgs and launchActivity options cannot both be specified in the launch configuration.');
+            this.sendEvent(new TerminatedEvent(false));
+            return;
+        }
+
         // set the custom ADB port - this should be changed to pass it to each ADBClient instance
         if (typeof args.adbPort === 'number' && args.adbPort >= 0 && args.adbPort <= 65535) {
             ADBSocket.ADBPort = args.adbPort;
@@ -378,16 +398,24 @@ class AndroidDebugSession extends DebugSession {
         }
     }
 
-    startLaunchActivity(launchActivity) {
+    async startLaunchActivity(launchActivity) {
         if (!launchActivity) {
-            if (!(launchActivity = this.apk_file_info.manifest.launcher)) {
-                throw new Error('No valid launch activity found in AndroidManifest.xml or launch.json');
+            // we're allowed no launchActivity if we have a custom am start command
+            if (!this.am_start_args) {
+                if (!(launchActivity = this.apk_file_info.manifest.launcher)) {
+                    throw new Error('No valid launch activity found in AndroidManifest.xml or launch.json');
+                }
             }
         }
 
-        const build = new BuildInfo(this.apk_file_info.manifest.package, new Map(this.src_packages.packages), launchActivity);
-        this.LOG(`Launching ${build.pkgname}/${launchActivity} on device ${this._device.serial} [API:${this.device_api_level||'?'}]`);
-        return this.dbgr.startDebugSession(build, this._device.serial);
+        const build = new BuildInfo(this.apk_file_info.manifest.package, new Map(this.src_packages.packages), launchActivity, this.am_start_args);
+
+        this.LOG(`Launching on device ${this._device.serial} [API:${this.device_api_level||'?'}]`);
+        if (this.am_start_args) {
+            this.LOG(`Using custom launch arguments '${this.am_start_args.join(' ')}'`);
+        }
+        const am_stdout = await this.dbgr.startDebugSession(build, this._device.serial);
+        this.LOG(am_stdout);
     }
 
     async configureAPISourcePath() {
@@ -440,7 +468,8 @@ class AndroidDebugSession extends DebugSession {
         })
         // send the install command
         this.LOG('Installing...');
-        const command = `pm install ${Array.isArray(this.pmInstallArgs) ? this.pmInstallArgs.join(' ') : '-r'} ${device_apk_fpn}`;
+        const pm_install_args = Array.isArray(this.pm_install_args) ? this.pm_install_args.join(' ') : '-r';
+        const command = `pm install ${pm_install_args} ${device_apk_fpn}`;
         D(command);
         const stdout = await this._device.adbclient.shell_cmd({
             command,

src/debugger-types.js

@@ -9,13 +9,14 @@ class BuildInfo {
      * @param {string} pkgname 
      * @param {Map<string,PackageInfo>} packages 
      * @param {string} launchActivity 
+     * @param {string[]} amCommandArgs custom arguments passed to `am start`
      */
-    constructor(pkgname, packages, launchActivity) {
+    constructor(pkgname, packages, launchActivity, amCommandArgs) {
         this.pkgname = pkgname;
         this.packages = packages;
         this.launchActivity = launchActivity;
         /** the arguments passed to `am start` */
-        this.startCommandArgs = [
+        this.startCommandArgs = amCommandArgs || [
             '-D',   // enable debugging
             '--activity-brought-to-front',
             '-a android.intent.action.MAIN',

src/debugger.js

@@ -29,7 +29,7 @@ const {
     TypeNotAvailable,
 } = require('./debugger-types');
 
-class  Debugger extends EventEmitter {
+class Debugger extends EventEmitter {
 
     constructor () {
         super();
@@ -76,7 +76,7 @@ class  Debugger extends EventEmitter {
      */
     async startDebugSession(build, deviceid) {
         this.session = new DebugSession(build, deviceid);
-        await Debugger.runApp(deviceid, build.startCommandArgs, build.postLaunchPause);
+        const stdout = await Debugger.runApp(deviceid, build.startCommandArgs, build.postLaunchPause);
 
         // retrieve the list of debuggable processes
         const pids = await this.getDebuggablePIDs(this.session.deviceid);
@@ -84,6 +84,7 @@ class  Debugger extends EventEmitter {
         const pid = pids[pids.length - 1];
         // after connect(), the caller must call resume() to begin
         await this.connect(pid);
+        return stdout;
     }
 
     /**
@@ -94,7 +95,7 @@ class  Debugger extends EventEmitter {
     static async runApp(deviceid, launch_cmd_args, post_launch_pause = 1000) {
         // older (<3) versions of Android only allow target components to be specified with -n
         const shell_cmd = {
-            command: 'am start ' + launch_cmd_args.join(' '),
+            command: `am start ${launch_cmd_args.join(' ')}`,
         };
         let retries = 10
         for (;;) {
@@ -104,12 +105,14 @@ class  Debugger extends EventEmitter {
             await sleep(post_launch_pause);
             // failures:
             //  Error: Activity not started...
-            const m = stdout.match(/Error:.*/g);
+            // /system/bin/sh: syntax error: unexpected EOF - this happens with invalid am command arguments
+            const m = stdout.match(/Error:.*|syntax error:/gi);
             if (!m) {
-                break;
+                // return the stdout from am (it shows the fully qualified component name)
+                return stdout.toString().trim();
             }
             else if (retries <= 0){
-                throw new Error(m[0]);
+                throw new Error(stdout.toString().trim());
             }
             retries -= 1;
         }