@aiot-toolkit/emulator 2.0.2-beta.3 → 2.0.2-beta.5

package/README.md

@@ -1,2 +1,15 @@
+## emulator
 
-emulator tool
+QEMU模拟器
+
+模拟器的介绍可参考[开发帮助文档](https://xiaomi.f.mioffice.cn/docx/doxk4Rk6x67GanHlzQ8bEOrxtEe)里的「模拟器」章节
+
+## 目录结构
+
+| 目录     | 描述                                                                            |
+| -------- | ------------------------------------------------------------------------------- |
+| avd   |   模拟器的AVD，配置统一放置$HOME/.android/avd目录下         |
+| instance | 模拟器实例，不同的Vela镜像版本会使用不同的instance，通过findInstance确定                 |
+| static   | 创建AVD时需要用到的静态资源，常量配置文件                                           |
+| typing    | 接口定义                                                       |
+| utils   | 工具函数                                                       |

package/lib/avd/index.d.ts

@@ -3,10 +3,22 @@ declare class VelaAvdCls {
     private avdHome;
     private sdkHome;
     constructor(avdResourcePaths: IAvdResourcePaths);
+    /**
+     * 创建Vela端的AVD，统一保存在.android目录下
+     * 1. 创建.android/advancedFeatures.ini文件
+     * 2. 创建.android/${avdName}.ini文件
+     * 3. 创建.android/${avdName}.avd/config.ini文件
+     * @param avdParams AVD参数，宽高、绑定的镜像路径等
+     * @returns
+     */
     createVelaAvd(avdParams: IAvdParams): boolean;
+    /** 根据AVD名字获取模拟器的详细信息 */
     getVelaAvdInfo(avdName: string): IAvdParams;
+    /** 根据名字删除AVD */
     deleteVelaAvd(avdName: string): boolean;
+    /** 获取已经创建的模拟器列表 */
     getVelaAvdList(): IAvdParams[];
+    /** 获取模拟器皮肤列表 */
     getVelaSkinList(): string[];
 }
 export default VelaAvdCls;

package/lib/avd/index.js

@@ -26,6 +26,14 @@ class VelaAvdCls {
             fs_1.default.mkdirSync(this.avdHome, { recursive: true });
         }
     }
+    /**
+     * 创建Vela端的AVD，统一保存在.android目录下
+     * 1. 创建.android/advancedFeatures.ini文件
+     * 2. 创建.android/${avdName}.ini文件
+     * 3. 创建.android/${avdName}.avd/config.ini文件
+     * @param avdParams AVD参数，宽高、绑定的镜像路径等
+     * @returns
+     */
     createVelaAvd(avdParams) {
         // 在.android下创建advancedFeatures.ini文件
         const advancedFeaturesIni = path_1.default.resolve(os_1.default.homedir(), '.android/advancedFeatures.ini');
@@ -76,6 +84,7 @@ class VelaAvdCls {
             throw (`createVelaAvd: ${e.message}`);
         }
     }
+    /** 根据AVD名字获取模拟器的详细信息 */
     getVelaAvdInfo(avdName) {
         const avdInfo = {
             avdName,
@@ -112,6 +121,7 @@ class VelaAvdCls {
             return avdInfo;
         }
     }
+    /** 根据名字删除AVD */
     deleteVelaAvd(avdName) {
         const avdDir = path_1.default.resolve(this.avdHome, `${avdName}.avd`);
         const avdIni = path_1.default.resolve(this.avdHome, `${avdName}.ini`);
@@ -124,6 +134,7 @@ class VelaAvdCls {
             return false;
         }
     }
+    /** 获取已经创建的模拟器列表 */
     getVelaAvdList() {
         const avdList = [];
         const files = fs_1.default.readdirSync(this.avdHome);
@@ -138,6 +149,7 @@ class VelaAvdCls {
         }
         return avdList;
     }
+    /** 获取模拟器皮肤列表 */
     getVelaSkinList() {
         try {
             const skinList = [];

package/lib/instance/index.d.ts

@@ -3,5 +3,11 @@ import CommonInstance from './common';
 import GoldfishInstance from './dev';
 import MiwearInstance from "./miwear";
 import OldGoldfishInstance from './preDev';
+/**
+ * 根据镜像决定使用哪个instance
+ * Vela正式版(4.0) -> MiwearInstance
+ * Vela开发版（dev, 0.0.2) -> OldGoldfishInstance
+ * Vela开发版（dev)，除0.0.2的其他版本 -> GoldfishInstance
+ */
 declare function findInstance(avdName: string, params: INewGoldfishInstanceParams): GoldfishInstance | MiwearInstance | OldGoldfishInstance | undefined;
 export { CommonInstance, GoldfishInstance, MiwearInstance, OldGoldfishInstance, findInstance };

package/lib/instance/index.js

@@ -14,6 +14,12 @@ const miwear_1 = __importDefault(require("./miwear"));
 exports.MiwearInstance = miwear_1.default;
 const preDev_1 = __importDefault(require("./preDev"));
 exports.OldGoldfishInstance = preDev_1.default;
+/**
+ * 根据镜像决定使用哪个instance
+ * Vela正式版(4.0) -> MiwearInstance
+ * Vela开发版（dev, 0.0.2) -> OldGoldfishInstance
+ * Vela开发版（dev)，除0.0.2的其他版本 -> GoldfishInstance
+ */
 function findInstance(avdName, params) {
     const { sdkHome, avdHome } = params;
     const { avdImagePath } = new avd_1.default({ sdkHome, avdHome }).getVelaAvdInfo(avdName);

package/lib/instance/miwear.d.ts

@@ -2,27 +2,69 @@ import { INewGoldfishInstanceParams, IStartOptions } from '../typing/Instance';
 import CommonInstance from './common';
 /**
  * MiwearInstance
- * 针对 vela4.0 的镜像
+ * 针对 Vela正式版（4.0）的镜像
  */
 declare class MiwearInstance extends CommonInstance {
+    private params;
     private appPathInEmulator;
     private debugSocket?;
     private reconnectCount;
     constructor(params: INewGoldfishInstanceParams);
-    /** 在goldfish模拟器中运行快应用 */
+    /**
+     * 1. 启动模拟器
+     * 2. 启动成功后，adb连接模拟器
+     * 3. 连接成功后，在模拟器中启动快应用
+     */
     start(options: IStartOptions): Promise<void>;
-    /** 启动goldfish模拟器 */
+    /**
+     * 启动模拟器
+     * 1. 通过options生成模拟器的启动命令
+     * 2. 执行启动命令
+     * 3. 判断模拟器是否启动成功
+     *    3.1 若disableNSH=true，输出流中匹配到/quickapp_rpk_installer_init|rpk installer init done/，认为模拟器启动成功了
+     *    3.2 若disableNSH=false，认为8s过后模拟器启动成功了
+     * @param options
+     * @returns
+     */
     startGoldfish(options: IStartOptions): Promise<void>;
-    /** 通过adb连接模拟器 */
+    /**
+     * 通过adb连接模拟器。
+     * 时间限制为10分钟，超时则表示连接失败
+     * @returns
+     */
     connectGoldfish(): Promise<boolean>;
-    /** 在goldfish中启动快应用 */
+    /**
+     * 在模拟器中启动快应用
+     * 1. 检查release目录是否有打包好的rpk
+     * 2. 检查当前是否为调试模式.
+     *    若是，将debugger_ip.cfg推到模拟器的/data/目录下
+     *    若否，则要删除模拟器中已有的data/debugger_ip.cfg
+     * 3. 调用installRpkToAppList将当前快应用安装到模拟器的应用列表中
+     * @param options
+     */
     startupQuickApp(options: IStartOptions): Promise<void>;
-    /** 将快应用安装到应用列表 */
+    /**
+     * 将快应用安装到模拟器的应用列表
+     * 1. 使用adb push将打包好的rpk推到模拟器的/data/quickapp/app/
+     * 2. nsh中调用pm install命令安装应用
+     * @param rpkPath rpk的绝对目录
+     * @param targetDir 要将rpk放到模拟器的哪个目录下
+     */
     installRpkToAppList(rpkPath: string, targetDir: string): Promise<void>;
-    initDebugSocket(): Promise<void> | undefined;
-    /** 通知模拟器更新 */
+    /** 连接模拟器中的调试服务，创建debugSocket
+     * 主要用于热更新时，通过debugSocket通知调试服务更新页面
+     * 设置了重连机制，会重复连接8次
+     */
+    initDebugSocket(): Promise<void>;
+    /** 通知模拟器更新
+     * 1. 确保已经成功连接模拟器中的调试服务
+     * 2. 使用adb push将build文件下的内容推到/data/quickapp/app/${packageName}
+     * 3. 发送Page.reload命令给调试服务，通知更新
+    */
     handleUpdate(): Promise<void>;
-    /** 创建server */
+    /**
+     * 创建server端，监听打包过程中client端发来的消息
+     */
     createWebsockeServer(): Promise<void>;
 }
 export default MiwearInstance;

package/lib/instance/miwear.js

@@ -35,7 +35,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const JavascriptDefaultCompileOption_1 = __importDefault(require("@aiot-toolkit/aiotpack/lib/compiler/javascript/JavascriptDefaultCompileOption"));
 const ColorConsole_1 = __importDefault(require("@aiot-toolkit/shared-utils/lib/ColorConsole"));
 const adbMiwt = __importStar(require("@miwt/adb"));
 const child_process_1 = require("child_process");
@@ -50,15 +49,20 @@ const common_1 = __importDefault(require("./common"));
 const MAX_RECONNECT_COUNT = 8;
 /**
  * MiwearInstance
- * 针对 vela4.0 的镜像
+ * 针对 Vela正式版（4.0）的镜像
  */
 class MiwearInstance extends common_1.default {
     constructor(params) {
         super(params);
+        this.params = params;
         this.appPathInEmulator = '/data/quickapp/app';
         this.reconnectCount = 0;
     }
-    /** 在goldfish模拟器中运行快应用 */
+    /**
+     * 1. 启动模拟器
+     * 2. 启动成功后，adb连接模拟器
+     * 3. 连接成功后，在模拟器中启动快应用
+     */
     start(options) {
         return __awaiter(this, void 0, void 0, function* () {
             this.startOptions = options;
@@ -68,9 +72,11 @@ class MiwearInstance extends common_1.default {
             const connected = yield this.connectGoldfish();
             if (connected) {
                 ColorConsole_1.default.info('### Emulator ### Goldfish emulator connected successfully');
+                // 如果是首次启动，创建server端监听事件
                 if (this.isFirstStart && this.startOptions.serverPort) {
                     yield this.createWebsockeServer();
                 }
+                // 在模拟器中启动快应用
                 this.startupQuickApp(options);
                 this.isFirstStart = false;
             }
@@ -79,13 +85,24 @@ class MiwearInstance extends common_1.default {
             }
         });
     }
-    /** 启动goldfish模拟器 */
+    /**
+     * 启动模拟器
+     * 1. 通过options生成模拟器的启动命令
+     * 2. 执行启动命令
+     * 3. 判断模拟器是否启动成功
+     *    3.1 若disableNSH=true，输出流中匹配到/quickapp_rpk_installer_init|rpk installer init done/，认为模拟器启动成功了
+     *    3.2 若disableNSH=false，认为8s过后模拟器启动成功了
+     * @param options
+     * @returns
+     */
     startGoldfish(options) {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {
             const { avdName, devtool } = options;
+            // 获取emulator bin的绝对路径
             const emulatorBin = this.getEmulatorBinPath();
             ColorConsole_1.default.log(`### Emulator ### emulator path: ${emulatorBin}`);
+            // 获取vela镜像的绝对路径
             const avdInfo = this.velaAvdCls.getVelaAvdInfo(avdName);
             const { avdArch, avdImagePath } = avdInfo;
             this.adbPort = yield portfinder_1.default.getPortPromise({ port: this.adbPort });
@@ -95,15 +112,15 @@ class MiwearInstance extends common_1.default {
             }
             const nuttxBinPath = path_1.default.resolve(avdImagePath, 'nuttx');
             ColorConsole_1.default.log(`### Emulator ### nuttx path: ${nuttxBinPath}`);
-            // 端口映射
+            // 端口映射，adb端口和debug端口
             let portMappingStr = `-network-user-mode-options hostfwd=tcp:127.0.0.1:${this.adbPort}-10.0.2.15:5555`;
             if (devtool) {
                 this.debugPort = yield portfinder_1.default.getPortPromise({ port: this.debugPort });
                 portMappingStr += `,hostfwd=tcp:127.0.0.1:${this.debugPort}-10.0.2.15:101`;
             }
             // 文件系统配置，第一次使用fatfs镜像挂载，后续使用adb push更新应用
-            const systemImageBin = path_1.default.resolve(avdImagePath, 'vela_resource.img');
-            const dataImageBin = path_1.default.resolve(avdImagePath, 'data.img');
+            const systemImageBin = path_1.default.resolve(avdImagePath, 'vela_resource.bin');
+            const dataImageBin = path_1.default.resolve(avdImagePath, 'vela_data.bin');
             const coreBin = path_1.default.resolve(avdImagePath, 'coredump.core');
             const imageMountStr = `-drive index=0,id=system,if=none,format=raw,file=${systemImageBin} \
 -device virtio-blk-device,bus=virtio-mmio-bus.0,drive=system \
@@ -120,8 +137,9 @@ class MiwearInstance extends common_1.default {
                 const portSuffix = this.startOptions.vncPort - constants_1.defaultVncPort;
                 vncStr = `-vnc :${portSuffix}`;
             }
+            // 根据disableNSH参数配置stdio
             const stdioType = options.disableNSH ? 'pipe' : 'inherit';
-            // 启动goldfish的命令和参数
+            // 启动模拟器的命令和参数
             const cmd = `${emulatorBin} -nuttx -avd ${avdName} -avd-arch ${avdArch} -show-kernel -kernel ${nuttxBinPath} ${portMappingStr} ${windowStr} -qemu ${vncStr} ${imageMountStr}`;
             const spawnArgs = cmd.split(' ');
             const spawnBin = spawnArgs.shift();
@@ -129,16 +147,19 @@ class MiwearInstance extends common_1.default {
             return new Promise((resolve) => {
                 var _a, _b, _c;
                 this.goldfishProcess = (0, child_process_1.spawn)(spawnBin, spawnArgs, { stdio: stdioType, shell: true, cwd: this.sdkHome });
+                // 监听错误流
                 (_a = this.goldfishProcess.stderr) === null || _a === void 0 ? void 0 : _a.on('data', (data) => {
                     const stderrCb = options.stderrCallback || console.log;
                     stderrCb(data.toString());
                 });
+                // 监听模拟器的退出事件
                 this.goldfishProcess.on('exit', (code) => {
                     ColorConsole_1.default.error(`### Emulator ### Goldfish emulator exited with code ${code}`);
                     if (options.exitCallback) {
                         options.exitCallback(code);
                     }
                 });
+                // disableNSH=false时，输出流会直接定向到终端，可在终端输入「回车」进入模拟器的终端，这种情况下无法拿到stdout中的数据
                 if (options.disableNSH) {
                     (_c = (_b = this.goldfishProcess) === null || _b === void 0 ? void 0 : _b.stdout) === null || _c === void 0 ? void 0 : _c.on('data', (data) => {
                         const msg = data.toString();
@@ -151,17 +172,20 @@ class MiwearInstance extends common_1.default {
                     });
                 }
                 else {
+                    // disableNSH=true时，默认8s后模拟器启动成功
                     setTimeout(() => {
                         ColorConsole_1.default.info(`### Emulator ### Goldfish emulator starts successfully`);
                         resolve();
                     }, 8000);
-                    ColorConsole_1.default.info(`### Emulator ### Goldfish emulator starts successfully`);
-                    resolve();
                 }
             });
         });
     }
-    /** 通过adb连接模拟器 */
+    /**
+     * 通过adb连接模拟器。
+     * 时间限制为10分钟，超时则表示连接失败
+     * @returns
+     */
     connectGoldfish() {
         return __awaiter(this, void 0, void 0, function* () {
             let adbConnected = false;
@@ -175,6 +199,7 @@ class MiwearInstance extends common_1.default {
                     ColorConsole_1.default.log(`### Emulator ### Excuting adb cmd: ${adbConnectCmd}`);
                     const str = yield adbMiwt.execAdbCmdAsync(adbConnectCmd);
                     ColorConsole_1.default.log(`### Emulator ### ${str}`);
+                    // 查询模拟器的状态是否为“device”
                     const devices = yield adbMiwt.getAdbDevices();
                     ColorConsole_1.default.log(`### Emulator ### adb devices: ${JSON.stringify(devices)}`);
                     adbConnected =
@@ -191,15 +216,26 @@ class MiwearInstance extends common_1.default {
             return adbConnected;
         });
     }
-    /** 在goldfish中启动快应用 */
+    /**
+     * 在模拟器中启动快应用
+     * 1. 检查release目录是否有打包好的rpk
+     * 2. 检查当前是否为调试模式.
+     *    若是，将debugger_ip.cfg推到模拟器的/data/目录下
+     *    若否，则要删除模拟器中已有的data/debugger_ip.cfg
+     * 3. 调用installRpkToAppList将当前快应用安装到模拟器的应用列表中
+     * @param options
+     */
     startupQuickApp(options) {
+        var _a;
         return __awaiter(this, void 0, void 0, function* () {
             const { package: appPackageName } = this.projectInfo;
-            const releaseDir = path_1.default.resolve(this.projectPath, JavascriptDefaultCompileOption_1.default.releasePath || 'dist');
+            const releaseDir = this.isRpk
+                ? path_1.default.resolve(this.projectPath, '../')
+                : path_1.default.resolve(this.projectPath, ((_a = this.params.compilerOption) === null || _a === void 0 ? void 0 : _a.releasePath) || 'dist');
             const files = fs_extra_1.default
                 .readdirSync(releaseDir)
                 .filter(item => item.includes(appPackageName) && item.endsWith('.rpk'));
-            if (files.length < 0) {
+            if (files.length === 0) {
                 ColorConsole_1.default.error(`### Emulator the rpk does not exist`);
             }
             const rpkPath = path_1.default.resolve(releaseDir, files[0]);
@@ -215,68 +251,75 @@ class MiwearInstance extends common_1.default {
             this.installRpkToAppList(rpkPath, this.appPathInEmulator);
         });
     }
-    /** 将快应用安装到应用列表 */
+    /**
+     * 将快应用安装到模拟器的应用列表
+     * 1. 使用adb push将打包好的rpk推到模拟器的/data/quickapp/app/
+     * 2. nsh中调用pm install命令安装应用
+     * @param rpkPath rpk的绝对目录
+     * @param targetDir 要将rpk放到模拟器的哪个目录下
+     */
     installRpkToAppList(rpkPath, targetDir) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 const sn = `127.0.0.1:${this.adbPort}`;
                 const { package: packageName } = this.projectInfo;
-                const rpkName = path_1.default.basename(rpkPath);
-                // 1. 查询应用是否已经安装，如果安装了，则先卸载
-                const lsCmd = `adb -s ${sn} shell ls ${this.appPathInEmulator}`;
-                const res = yield adbMiwt.execAdbCmdAsync(lsCmd);
-                if (res.includes(packageName)) {
-                    const uninstallCmd = `adb -s ${sn} shell pm uninstall ${packageName}`;
-                    ColorConsole_1.default.info(`### Emulator ### Excuting cmd: ${uninstallCmd}`);
-                    adbMiwt.execAdbCmdAsync(uninstallCmd);
-                    // 这里等待2s的作用是等qemu执行完uninstall操作的一系列工作
-                    yield (0, utils_1.sleep)(2000);
-                }
-                // 2. adb push应用的rpk
+                // 1. adb push应用的rpk
                 const targetPath = `${targetDir}/${packageName}.rpk`;
-                const pushCmd = `adb -s ${sn} push ${rpkPath} ${targetPath}`;
+                const pushCmd = `adb -s ${sn} push "${rpkPath}" ${targetPath}`;
                 ColorConsole_1.default.info(`### Emulator ### Excuting cmd: ${pushCmd}`);
                 yield adbMiwt.execAdbCmdAsync(pushCmd);
-                yield (0, utils_1.sleep)(100);
-                // 3. 安装应用
+                yield (0, utils_1.sleep)(1000);
+                // 2. 安装应用(pm install时如何应用重名会覆盖)
                 const installCmd = `adb -s ${sn} shell pm install ${targetPath}`;
                 ColorConsole_1.default.info(`### Emulator ### Excuting cmd: ${installCmd}`);
                 adbMiwt.execAdbCmdAsync(installCmd);
             }
-            catch (e) { }
+            catch (e) {
+                ColorConsole_1.default.error(`### Emulator ### ${e.message}`);
+            }
         });
     }
+    /** 连接模拟器中的调试服务，创建debugSocket
+     * 主要用于热更新时，通过debugSocket通知调试服务更新页面
+     * 设置了重连机制，会重复连接8次
+     */
     initDebugSocket() {
-        if (this.debugSocket && this.debugSocket.OPEN) {
-            return Promise.resolve();
-        }
-        this.debugSocket = new ws_1.default(`ws://localhost:${this.debugPort}`);
-        this.debugSocket.onopen = () => {
-            ColorConsole_1.default.info(`### Emulator debugSocket connect success`);
-            return Promise.resolve();
-        };
-        this.debugSocket.onerror = (e) => {
-            var _a;
-            // 重连机制
-            (_a = this.debugSocket) === null || _a === void 0 ? void 0 : _a.terminate();
-            if (this.reconnectCount < MAX_RECONNECT_COUNT) {
-                ColorConsole_1.default.info(`### Emulator the ${this.reconnectCount + 1}th time to reconnect debug server`);
-                this.reconnectCount++;
-                setTimeout(() => this.initDebugSocket(), 2000);
+        return new Promise((resolve, reject) => {
+            if (this.debugSocket && this.debugSocket.OPEN) {
+                return resolve();
             }
-            else {
+            this.debugSocket = new ws_1.default(`ws://localhost:${this.debugPort}`);
+            this.debugSocket.onopen = () => {
+                ColorConsole_1.default.info(`### Emulator debugSocket connect success`);
+                return resolve();
+            };
+            this.debugSocket.onerror = (errorEvent) => {
+                var _a;
+                // 重连机制
+                (_a = this.debugSocket) === null || _a === void 0 ? void 0 : _a.terminate();
+                if (this.reconnectCount < MAX_RECONNECT_COUNT) {
+                    ColorConsole_1.default.info(`### Emulator the ${this.reconnectCount + 1}th time to reconnect debug server`);
+                    this.reconnectCount++;
+                    setTimeout(() => this.initDebugSocket(), 2000);
+                }
+                else {
+                    this.debugSocket = undefined;
+                    this.reconnectCount = 0;
+                    return reject(`### Emulator debugSocket connect failed, ${errorEvent.message}`);
+                }
+            };
+            this.debugSocket.onclose = (closeEvent) => {
                 this.debugSocket = undefined;
                 this.reconnectCount = 0;
-                return Promise.reject(`### Emulator debugSocket connect failed`);
-            }
-        };
-        this.debugSocket.onclose = (e) => {
-            this.debugSocket = undefined;
-            this.reconnectCount = 0;
-            ColorConsole_1.default.log(`### Emulator debugSocket connect close: ${e.data}`);
-        };
+                ColorConsole_1.default.log(`### Emulator debugSocket connect close: ${closeEvent.reason}`);
+            };
+        });
     }
-    /** 通知模拟器更新 */
+    /** 通知模拟器更新
+     * 1. 确保已经成功连接模拟器中的调试服务
+     * 2. 使用adb push将build文件下的内容推到/data/quickapp/app/${packageName}
+     * 3. 发送Page.reload命令给调试服务，通知更新
+    */
     handleUpdate() {
         var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
@@ -286,12 +329,13 @@ class MiwearInstance extends common_1.default {
                 // 1. 将整包重新推到miwear中（TODO：增量更新）
                 const sn = `127.0.0.1:${this.adbPort}`;
                 const { package: appPackageName } = this.projectInfo;
-                // windows平台adb push时无法使用通配符，需另外处理
-                if (os_1.default.platform() === 'win32') {
+                // windows平台adb push时无法使用通配符，需另外处理; 
+                // 项目路径包含空格时，无法通过加引号来使用 * 通配符
+                if (os_1.default.platform() === 'win32' || this.projectPath.indexOf(' ') > 0) {
                     const rmCmd = `adb -s ${sn} shell rm -r ${this.appPathInEmulator}/${appPackageName}`;
                     yield adbMiwt.execAdbCmdAsync(rmCmd);
                     const sourcePath = path_1.default.resolve(this.projectPath, './build');
-                    const pushCmd = `adb -s ${sn} push ${sourcePath} ${this.appPathInEmulator}/${appPackageName}`;
+                    const pushCmd = `adb -s ${sn} push "${sourcePath}" ${this.appPathInEmulator}/${appPackageName}`;
                     yield adbMiwt.execAdbCmdAsync(pushCmd);
                 }
                 else {
@@ -309,7 +353,9 @@ class MiwearInstance extends common_1.default {
             }
         });
     }
-    /** 创建server */
+    /**
+     * 创建server端，监听打包过程中client端发来的消息
+     */
     createWebsockeServer() {
         var _a;
         return __awaiter(this, void 0, void 0, function* () {
@@ -321,6 +367,7 @@ class MiwearInstance extends common_1.default {
                 socket.on('error', err => {
                     ColorConsole_1.default.error(`### App Socket server ### Websocket server error: ${err.message}`);
                 });
+                // data的格式：{ type: string, data: any }
                 socket.on('message', (data) => __awaiter(this, void 0, void 0, function* () {
                     var _a;
                     const message = JSON.parse(data.toString());

package/lib/instance/preDev.d.ts

@@ -2,20 +2,54 @@
 import { ChildProcess } from 'child_process';
 import { INewGoldfishInstanceParams, IStartOptions } from '../typing/Instance';
 import CommonInstance from './common';
+/**
+ * OldGoldfishInstance
+ * 针对 Vela开发版（dev, 0.0.2）的镜像
+ */
 declare class OldGoldfishInstance extends CommonInstance {
     private host9pPort;
     v9fsProcess: ChildProcess | undefined;
     constructor(params: INewGoldfishInstanceParams);
-    /** 在goldfish模拟器中运行快应用 */
+    /**
+     * 1. 启动9p server
+     * 2. 将打包好的rpk推到host的挂载目录
+     * 3. 启动模拟器
+     * 4. 模拟器启动成功后，adb连接模拟器
+     * 5. 连接成功后，在模拟器中启动快应用
+     */
     start(options: IStartOptions): Promise<void>;
-    /** 在goldfish中启动快应用 */
+    /**
+     * 在模拟器中启动快应用（快应用都在模拟器的/data/app目录下）
+     * 1. 是否为调试模式
+     *    若是，在模拟器终端执行vapp app/${packageName} &
+     *    若否，在模拟器终端执行vapp --jsdebugger=10.0.2.15:101 app/${packageName} &
+     */
     startupQuickApp(options: IStartOptions): void;
-    /** host启动9pServer */
+    /** host启动9pServer
+     * 作用是将本地的quickappMountDir目录挂载到模拟器的/data目录
+    */
     ensure9pServerRunnning(): Promise<void>;
-    /** 启动goldfish模拟器 */
+    /**
+     * 启动模拟器
+     * 1. 通过options生成模拟器的启动命令
+     * 2. 执行启动命令
+     * 3. 判断模拟器是否启动成功
+     *    3.1 若disableNSH=true，输出流中匹配到/quickapp_rpk_installer_init|rpk installer init done/，认为模拟器启动成功了
+     *    3.2 若disableNSH=false，认为8s过后模拟器启动成功了
+     * @param options
+     * @returns
+     */
     startGoldfish(options: IStartOptions): Promise<void>;
-    /** 通过adb连接模拟器 */
+    /**
+     * 通过adb连接模拟器。
+     * 时间限制为10分钟，超时则表示连接失败
+     * @returns
+     */
     connectGoldfish(): Promise<boolean>;
+    /**
+     * 推送文件到本地的${sdkHome}/qa/app/${packageName}目录
+     * @param sourceRoot 源目录
+     */
     pushRpk(sourceRoot: string): Promise<void>;
     /** 停止模拟器并释放相关资源 */
     stop(): Promise<void>;

package/lib/instance/preDev.js

@@ -46,12 +46,22 @@ const path_1 = __importDefault(require("path"));
 const portfinder_1 = __importDefault(require("portfinder"));
 const constants_1 = require("../static/constants");
 const common_1 = __importDefault(require("./common"));
+/**
+ * OldGoldfishInstance
+ * 针对 Vela开发版（dev, 0.0.2）的镜像
+ */
 class OldGoldfishInstance extends common_1.default {
     constructor(params) {
         super(params);
         this.host9pPort = 7878;
     }
-    /** 在goldfish模拟器中运行快应用 */
+    /**
+     * 1. 启动9p server
+     * 2. 将打包好的rpk推到host的挂载目录
+     * 3. 启动模拟器
+     * 4. 模拟器启动成功后，adb连接模拟器
+     * 5. 连接成功后，在模拟器中启动快应用
+     */
     start(options) {
         return __awaiter(this, void 0, void 0, function* () {
             // host启动9p server
@@ -62,9 +72,11 @@ class OldGoldfishInstance extends common_1.default {
             this.pushRpk(buildedFilesPath);
             // 启动模拟器
             yield this.startGoldfish(options);
+            // adb连接快应用
             const connected = yield this.connectGoldfish();
             if (connected) {
                 ColorConsole_1.default.log('### Emulator ### Goldfish emulator connected successfully');
+                // 如果是首次启动，创建server端监听事件
                 if (this.isFirstStart && this.startOptions.serverPort) {
                     yield this.createWebsockeServer();
                 }
@@ -77,7 +89,12 @@ class OldGoldfishInstance extends common_1.default {
             }
         });
     }
-    /** 在goldfish中启动快应用 */
+    /**
+     * 在模拟器中启动快应用（快应用都在模拟器的/data/app目录下）
+     * 1. 是否为调试模式
+     *    若是，在模拟器终端执行vapp app/${packageName} &
+     *    若否，在模拟器终端执行vapp --jsdebugger=10.0.2.15:101 app/${packageName} &
+     */
     startupQuickApp(options) {
         try {
             const { package: packageName } = this.projectInfo;
@@ -86,6 +103,7 @@ class OldGoldfishInstance extends common_1.default {
             ColorConsole_1.default.log(`### Emulator ### Excuting adb cmd: ${mountCmd}`);
             adbMiwt.execAdbCmdSync(mountCmd);
             let vappCmd = `adb -s 127.0.0.1:${this.adbPort} shell vapp app/${packageName} &`;
+            // 调试情况下，需要加--jsdebugger=10.0.2.15:101
             if (options.devtool) {
                 vappCmd = `adb -s 127.0.0.1:${this.adbPort} shell vapp --jsdebugger=10.0.2.15:101 app/${packageName} &`;
             }
@@ -97,7 +115,9 @@ class OldGoldfishInstance extends common_1.default {
             ColorConsole_1.default.error(`### Emulator ### Failed to startup quickapp: ${e.message}`);
         }
     }
-    /** host启动9pServer */
+    /** host启动9pServer
+     * 作用是将本地的quickappMountDir目录挂载到模拟器的/data目录
+    */
     ensure9pServerRunnning() {
         return new Promise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -121,6 +141,7 @@ class OldGoldfishInstance extends common_1.default {
                 address,
                 '--debug'
             ]);
+            // 监听stderr，判断9p server是否启动成功了
             (_a = this.v9fsProcess.stderr) === null || _a === void 0 ? void 0 : _a.on('data', (data) => {
                 const output = data.toString();
                 if (output.match(/Server started, listening on: 127.0.0.1:(\d+)/)) {
@@ -129,18 +150,30 @@ class OldGoldfishInstance extends common_1.default {
                     return resolve();
                 }
             });
+            // 监听exit事件，判断9p server是否退出了
             this.v9fsProcess.on('exit', (code) => {
                 ColorConsole_1.default.error(`### Emulator ### ya-vm-file-server exited with code ${code}`);
                 return reject();
             });
         }));
     }
-    /** 启动goldfish模拟器 */
+    /**
+     * 启动模拟器
+     * 1. 通过options生成模拟器的启动命令
+     * 2. 执行启动命令
+     * 3. 判断模拟器是否启动成功
+     *    3.1 若disableNSH=true，输出流中匹配到/quickapp_rpk_installer_init|rpk installer init done/，认为模拟器启动成功了
+     *    3.2 若disableNSH=false，认为8s过后模拟器启动成功了
+     * @param options
+     * @returns
+     */
     startGoldfish(options) {
         return __awaiter(this, void 0, void 0, function* () {
             const { avdName, devtool } = options;
+            // 获取emulator bin的绝对路径
             const emulatorBin = this.getEmulatorBinPath();
             ColorConsole_1.default.log(`### Emulator ### emulator path: ${emulatorBin}`);
+            // 获取vela镜像的绝对路径
             const avdInfo = this.velaAvdCls.getVelaAvdInfo(avdName);
             const { avdArch, avdImagePath } = avdInfo;
             this.adbPort = yield portfinder_1.default.getPortPromise({ port: this.adbPort });
@@ -150,6 +183,7 @@ class OldGoldfishInstance extends common_1.default {
             }
             const nuttxBinPath = path_1.default.resolve(avdImagePath, 'nuttx');
             ColorConsole_1.default.log(`### Emulator ### nuttx path: ${nuttxBinPath}`);
+            // 端口映射，adb端口和debug端口
             let portMappingStr = `user,id=u1,hostfwd=tcp:127.0.0.1:${this.adbPort}-10.0.2.15:5555`;
             if (devtool) {
                 this.debugPort = yield portfinder_1.default.getPortPromise({ port: this.debugPort });
@@ -157,7 +191,6 @@ class OldGoldfishInstance extends common_1.default {
                 portMappingStr += `,hostfwd=tcp:127.0.0.1:${this.debugPort}-10.0.2.15:101`;
             }
             ColorConsole_1.default.log(`### Emulator ### Start qemu with TCP: ${portMappingStr}`);
-            const stdioType = options.disableNSH ? 'pipe' : 'inherit';
             // vnc配置
             let noWindow = false;
             let vncStr = '';
@@ -166,6 +199,8 @@ class OldGoldfishInstance extends common_1.default {
                 const portSuffix = options.vncPort - constants_1.defaultVncPort;
                 vncStr = `-vnc :${portSuffix}`;
             }
+            // 根据disableNSH参数配置stdio
+            const stdioType = options.disableNSH ? 'pipe' : 'inherit';
             // 启动goldfish的命令和参数
             const spawnBin = emulatorBin;
             const spawnArgs = [
@@ -189,16 +224,19 @@ class OldGoldfishInstance extends common_1.default {
             return new Promise((resolve) => {
                 var _a;
                 this.goldfishProcess = (0, child_process_1.spawn)(spawnBin, spawnArgs, { stdio: stdioType, shell: true });
+                // 监听错误流
                 (_a = this.goldfishProcess.stderr) === null || _a === void 0 ? void 0 : _a.on('data', (data) => {
                     const stderrCb = options.stderrCallback || console.log;
                     stderrCb(data.toString());
                 });
+                // 监听模拟器的退出事件
                 this.goldfishProcess.on('exit', (code) => {
                     ColorConsole_1.default.error(`### Emulator ### Goldfish emulator exited with code ${code}`);
                     if (options.exitCallback) {
                         options.exitCallback(code);
                     }
                 });
+                // 监听输出流。输出了'(NSH)'标识或者2s后则认为模拟器启动成功
                 const p1 = new Promise((resolve) => {
                     var _a, _b;
                     (_b = (_a = this.goldfishProcess) === null || _a === void 0 ? void 0 : _a.stdout) === null || _b === void 0 ? void 0 : _b.on('data', (data) => {
@@ -218,7 +256,11 @@ class OldGoldfishInstance extends common_1.default {
             });
         });
     }
-    /** 通过adb连接模拟器 */
+    /**
+     * 通过adb连接模拟器。
+     * 时间限制为10分钟，超时则表示连接失败
+     * @returns
+     */
     connectGoldfish() {
         return __awaiter(this, void 0, void 0, function* () {
             let adbConnected = false;
@@ -248,6 +290,10 @@ class OldGoldfishInstance extends common_1.default {
             return adbConnected;
         });
     }
+    /**
+     * 推送文件到本地的${sdkHome}/qa/app/${packageName}目录
+     * @param sourceRoot 源目录
+     */
     pushRpk(sourceRoot) {
         return __awaiter(this, void 0, void 0, function* () {
             const { package: appPackageName } = this.projectInfo;

package/lib/static/constants.d.ts

@@ -6,14 +6,17 @@ export declare const defaultSkinHome: string;
 export declare const defaultQuickappHome: string;
 export declare const defaultToolsHome: string;
 export declare const defaultVncPort = 5900;
-export declare const emulatorEnvVersion: {
+export declare const VelaImageVersionList: {
+    label: string;
+    value: string;
+    time: string;
+}[];
+export declare const EmulatorEnvVersion: {
     name: string;
     emulator: string;
     qa: string;
     skins: string;
-    'system-images': {
-        release: string;
-        dev: string;
-    };
+    'system-images': string;
     tools: string;
+    modem_simulator: string;
 };

package/lib/static/constants.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.emulatorEnvVersion = exports.defaultVncPort = exports.defaultToolsHome = exports.defaultQuickappHome = exports.defaultSkinHome = exports.defaultEmulatorHome = exports.defaultImageHome = exports.defaultAvdHome = exports.defaultSDKHome = void 0;
+exports.EmulatorEnvVersion = exports.VelaImageVersionList = exports.defaultVncPort = exports.defaultToolsHome = exports.defaultQuickappHome = exports.defaultSkinHome = exports.defaultEmulatorHome = exports.defaultImageHome = exports.defaultAvdHome = exports.defaultSDKHome = void 0;
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 exports.defaultSDKHome = path_1.default.resolve(os_1.default.homedir(), '.export');
@@ -14,14 +14,24 @@ exports.defaultSkinHome = path_1.default.resolve(exports.defaultSDKHome, 'skins'
 exports.defaultQuickappHome = path_1.default.resolve(exports.defaultSDKHome, 'qa');
 exports.defaultToolsHome = path_1.default.resolve(exports.defaultSDKHome, 'tools');
 exports.defaultVncPort = 5900;
-exports.emulatorEnvVersion = {
+exports.VelaImageVersionList = [
+    {
+        label: 'vela正式版（4.0）',
+        value: 'vela-release-4.0',
+        time: '2024-04-10T04:10:00'
+    },
+    {
+        label: 'vela开发版（dev, 0.0.2）',
+        value: 'vela-dev-0.0.2',
+        time: '2023-12-04T16:31:00',
+    },
+];
+exports.EmulatorEnvVersion = {
     name: '模拟器资源版本管理',
-    emulator: '0.0.1',
+    emulator: '0.0.3',
     qa: '0.0.1',
     skins: '0.0.1',
-    'system-images': {
-        release: '4.0',
-        dev: '0.0.2'
-    },
-    tools: '0.0.2'
+    'system-images': exports.VelaImageVersionList[0].value,
+    tools: '0.0.2',
+    modem_simulator: '0.0.1'
 };

package/lib/typing/Instance.d.ts

@@ -1,8 +1,10 @@
 /// <reference types="node" />
+import IJavascriptCompileOption from "@aiot-toolkit/aiotpack/lib/compiler/javascript/interface/IJavascriptCompileOption";
 import { IAvdResourcePaths } from "./Avd";
 export interface INewGoldfishInstanceParams extends IAvdResourcePaths {
     projectPath: string;
     sourceRoot?: string;
+    compilerOption?: Partial<IJavascriptCompileOption>;
 }
 export interface IStartOptions {
     avdName: string;

package/lib/utils/index.d.ts

@@ -9,4 +9,5 @@ export declare function killProcessByPid(pid: string): void;
  * 根据命令杀死进程
  */
 export declare function killProcessByCmd(cmd: string): Promise<void>;
+/** 延迟函数 */
 export declare function sleep(time: number): Promise<void>;

package/lib/utils/index.js

@@ -79,6 +79,7 @@ function killProcessByCmd(cmd) {
     });
 }
 exports.killProcessByCmd = killProcessByCmd;
+/** 延迟函数 */
 function sleep(time) {
     return __awaiter(this, void 0, void 0, function* () {
         return new Promise(resolve => setTimeout(resolve, time));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiot-toolkit/emulator",
-  "version": "2.0.2-beta.3",
+  "version": "2.0.2-beta.5",
   "description": "vela emulator tool.",
   "homepage": "",
   "license": "ISC",
@@ -35,10 +35,14 @@
     "emulator"
   ],
   "dependencies": {
-    "@aiot-toolkit/aiotpack": "2.0.2-beta.3",
-    "@aiot-toolkit/shared-utils": "2.0.2-beta.3",
+    "@aiot-toolkit/aiotpack": "2.0.2-beta.5",
+    "@aiot-toolkit/shared-utils": "2.0.2-beta.5",
     "find-process": "^1.4.7",
     "portfinder": "^1.0.32"
   },
-  "gitHead": "8bfdd8895ffd8fc4aa1465779def5ab4392a7a4b"
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "fs-extra": "^11.2.0"
+  },
+  "gitHead": "8c18753992c453c6569a3125378e75fbf4760a1f"
 }