@flun/nodejs-mobile-gyp 1.2.1 → 1.2.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 变更日志
 
+## [1.2.3] - 2026-11-10 22:15
+### 优化
+- 整体细节优化+依赖包更新;
+
+## [1.2.2] - 2026-11-06 11:02
+### 优化
+- 细节优化;
+
 ## [1.2.1] - 2026-11-06 10:02
 ### 优化
 - 帮助文本层级改为与其它作用域包一致:`用法:` 缩进 2,分组名缩进 4,各条目缩进 6;
@@ -23,30 +31,4 @@
 
 ### 文档
 - README 的包目录结构同步磁盘实际内容:补 `gyp/pyproject.toml`、`gyp/README.md`、
-  `gyp/test_gyp.py`,移除不存在的 `gyp/LICENSE`;顶层文件按 `files` 顺序重排;
-
-## [1.2.0] - 2026-11-02 16:05
-### 新增
-- 帮助文本重写为中文三层结构:`用法:` 为 0 级,`命令:`/`选项:` 缩进 2,各条目缩进 4;
-  命令含别名 `ls`/`rm`,选项简写在前、完整写法置于行尾注释;末尾仅输出版本号行;
-- 无参数、`help`、`-h`、`--help` 均打印完整帮助并以 exit 0 退出;
-- 帮助文本按语义着色:`用法:` 用 `chalk.blueBright`,分组名用 `chalk.cyan`,命令与选项名用 `chalk.cyanBright`,
-  说明文字用 `chalk.gray`,末尾版本号用 `chalk.hex('#B8860B')`;非 TTY 下自动关闭颜色,不向管道泄漏 ANSI;
-- 未知命令提示着色:错误标记用 `chalk.red`,命令名用 `chalk.yellow`;
-
-### 修复
-- 未知命令改为输出 `✗ 未知命令: xxx` + 一个空行 + 完整帮助,并以 exit 1 退出;
-  此前未知参数不报错,静默继续;
-- `-h` 此前被忽略,现作为帮助入口;该行为变更可能影响依赖旧行为的脚本;
-- 帮助文本命令区与选项区说明列错位:命令区原补到显示列 17,选项区 23,现统一补到 23;
-  补白改为按显示宽度计算,中日韩全角字符按 2 列计,此前按码元计导致含中文的选项名整体左移;
-- `package.json` 的 `dependencies` 补声明 `chalk`;`lib/node-gyp.js` 已引用该模块,
-  此前未声明,从 npm 安装后缺少依赖会导致 `--help` 直接报错;
-
-### 文档
-- `lib/` 下 12 个 js 去除 BOM;`维护.md`、`package.json`、`lib/util.js` 换行符由 CRLF 改为 LF;
-
-## [1.1.4] - 2026-10-24 09:20
-### 优化
-- 项目标点已改为以英文标点为主;
-- 行宽改为以 123 为主,部分超宽表格改为了列表;
+  `gyp/test_gyp.py`,移除不存在的 `gyp/LICENSE`;顶层文件按 `files` 顺序重排;

package/bin/node-gyp.js

@@ -1,27 +1,23 @@
 #!/usr/bin/env node
-
+import chalk from 'chalk';
 import envPaths from 'env-paths';
-import os from 'os';
 import fs from 'fs';
-import chalk from 'chalk';
-import { Gyp } from '../lib/node-gyp.js';
+import os from 'os';
 import * as log from '../lib/log.js';
+import { Gyp } from '../lib/node-gyp.js';
 
 process.title = 'nodejs-mobile-gyp';
 /**
  * 处理并执行选中的命令;
  */
-
 const prog = new Gyp(), homeDir = os.homedir();
 let completed = false;
 prog.parseArgv(process.argv), prog.devDir = prog.opts.devdir;
 
 if (prog.devDir) prog.devDir = prog.devDir.replace(/^~/, homeDir);
 else if (homeDir) prog.devDir = envPaths('node-gyp', { suffix: '' }).cache;
-else {
-  throw new Error('nodejs-mobile-gyp 需要指定用户主目录,请设置环境变量 HOME 或 USERPROFILE;'
-    + '也可用 --devdir /path/to/.node-gyp 覆盖');
-}
+else throw new Error('nodejs-mobile-gyp 需要指定用户主目录,请设置环境变量 HOME 或 USERPROFILE;'
+  + '也可用 --devdir /path/to/.node-gyp 覆盖');
 
 if (prog.todo.length === 0) {
   const helpArgs = ['help', '-h', '--help'], hasHelp = process.argv.some(a => helpArgs.includes(a)),

package/lib/build.js

@@ -1,11 +1,11 @@
+import { spawnSync } from 'child_process';
+import fsSync from 'fs';
+import { glob } from 'glob';
 import gracefulFs from 'graceful-fs';
+import os from 'os';
 import path from 'path';
-import { glob } from 'glob';
-import * as log from './log.js';
 import which from 'which';
-import os from 'os';
-import { spawnSync } from 'child_process';
-import fsSync from 'fs';
+import * as log from './log.js';
 
 const fs = gracefulFs.promises, _hostIsWindows = process.platform === 'win32',
   // Android 交叉编译即使宿主是 Windows,也必须走 make(make-android 生成器)
@@ -65,151 +65,155 @@ const fs = gracefulFs.promises, _hostIsWindows = process.platform === 'win32',
       }
     }
     return null;
-  },
+  };
 
-  /**
-   * 调用 make/msbuild 构建原生模块
-   */
-  build = async (gyp, argv) => {
-    let platformMake = 'make';
+/**
+ * 调用 make/msbuild 构建原生模块
+ * >查看定义:@see {@link build}
+ * @param {object} gyp gyp 实例
+ * @param {string[]} argv 命令行参数
+ * @returns {Promise<void>}
+ */
+const build = async (gyp, argv) => {
+  let platformMake = 'make';
 
-    if (['aix', 'os400'].includes(process.platform) || process.platform.includes('bsd')) platformMake = 'gmake';
-    else if (win && argv.length > 0) argv = argv.map(target => '/t:' + target);
+  if (['aix', 'os400'].includes(process.platform) || process.platform.includes('bsd')) platformMake = 'gmake';
+  else if (win && argv.length > 0) argv = argv.map(target => '/t:' + target);
 
-    const makeCommand = gyp.opts.make || process.env.MAKE || platformMake, jobs = gyp.opts.jobs || process.env.JOBS;
-    let command = win ? 'msbuild' : makeCommand, buildType, config, arch, nodeDir, guessedSolution, python, buildBinsDir;
+  const makeCommand = gyp.opts.make || process.env.MAKE || platformMake, jobs = gyp.opts.jobs || process.env.JOBS;
+  let command = win ? 'msbuild' : makeCommand, buildType, config, arch, nodeDir, guessedSolution, python, buildBinsDir;
 
-    /**
-     * 真正启动子进程并编译模块
-     */
-    const doBuild = async () => {
-      // 启用 verbose 构建
-      const verbose = log.logger.isVisible('verbose');
-      let j;
+  /**
+   * 真正启动子进程并编译模块
+   */
+  const doBuild = async () => {
+    // 启用 verbose 构建
+    const verbose = log.logger.isVisible('verbose');
+    let j;
+
+    if (!win && verbose) argv.push('V=1');
+    if (win && !verbose) argv.push('/clp:Verbosity=minimal');
+    if (win) argv.push('/nologo'); // Windows 上关闭 Microsoft logo
+
+    // 指定构建类型,默认 Release
+    if (win) {
+      // 把 .gypi 配置中的 target_arch 转换为 MSBuild 的 /Platform
+      // 因为表示"32 位 Intel"的方式很多,默认按此处理
+      // 注意:msbuild 的 Condition 字符串相等比较不区分大小写
+      const archLower = arch.toLowerCase(), p = archLower === 'x64' ? 'x64' : (archLower === 'arm' ? 'ARM'
+        : (archLower === 'arm64' ? 'ARM64' : 'Win32'));
+      argv.push('/p:Configuration=' + buildType + ';Platform=' + p);
+      if (jobs) {
+        j = parseInt(jobs, 10)
+        if (!isNaN(j) && j > 0) argv.push('/m:' + j);
+        else if (jobs.toUpperCase() === 'MAX') argv.push('/m:' + os.cpus().length);
+      }
+    }
+    // 调用 build 目录下的 Makefile
+    else {
+      argv.push('BUILDTYPE=' + buildType), argv.push('-C'), argv.push('build');
+      if (jobs) {
+        j = parseInt(jobs, 10);
+        if (!isNaN(j) && j > 0) argv.push('--jobs'), argv.push(j);
+        else if (jobs.toUpperCase() === 'MAX') argv.push('--jobs'), argv.push(os.cpus().length);
+      }
+    }
 
-      if (!win && verbose) argv.push('V=1');
-      if (win && !verbose) argv.push('/clp:Verbosity=minimal');
-      if (win) argv.push('/nologo'); // Windows 上关闭 Microsoft logo
+    if (win) {
+      // 用户是否指定了自己的 .sln 文件?
+      const hasSln = argv.some(arg => path.extname(arg) === '.sln');
+      if (!hasSln) argv.unshift(gyp.opts.solution || guessedSolution);
+    }
 
-      // 指定构建类型,默认 Release
-      if (win) {
-        // 把 .gypi 配置中的 target_arch 转换为 MSBuild 的 /Platform
-        // 因为表示"32 位 Intel"的方式很多,默认按此处理
-        // 注意:msbuild 的 Condition 字符串相等比较不区分大小写
-        const archLower = arch.toLowerCase(), p = archLower === 'x64' ? 'x64' : (archLower === 'arm' ? 'ARM'
-          : (archLower === 'arm64' ? 'ARM64' : 'Win32'));
-        argv.push('/p:Configuration=' + buildType + ';Platform=' + p);
-        if (jobs) {
-          j = parseInt(jobs, 10)
-          if (!isNaN(j) && j > 0) argv.push('/m:' + j);
-          else if (jobs.toUpperCase() === 'MAX') argv.push('/m:' + os.cpus().length);
+    if (!win) {
+      // 把构建期依赖的符号链接(如 Python)加入 PATH
+      buildBinsDir = path.resolve('build', 'node_gyp_bins');
+      if (_hostIsWindows) {
+        const shellDir = findWindowsShellDir();
+        if (shellDir) {
+          process.env.PATH = `${shellDir};${process.env.PATH}`;
+          log.verbose('bin 环境', `已将 ${shellDir} 加入 PATH,供 make 使用`);
         }
+        else log.warn('shell 环境', '未找到 sh.exe;GNU make 的 Unix 命令可能失败;建议安装 Git for Windows');
       }
-      // 调用 build 目录下的 Makefile
-      else {
-        argv.push('BUILDTYPE=' + buildType), argv.push('-C'), argv.push('build');
-        if (jobs) {
-          j = parseInt(jobs, 10);
-          if (!isNaN(j) && j > 0) argv.push('--jobs'), argv.push(j);
-          else if (jobs.toUpperCase() === 'MAX') argv.push('--jobs'), argv.push(os.cpus().length);
+      process.env.PATH = _hostIsWindows ? `${buildBinsDir};${process.env.PATH}` : `${buildBinsDir}:${process.env.PATH}`;
+      await fs.mkdir(buildBinsDir, { recursive: true });
+
+      if (_hostIsWindows) {
+        // Windows 无 python3 名称,且创建符号链接需要管理员权限;改用 .cmd 桥接
+        const shimPath = path.join(buildBinsDir, 'python3.cmd');
+        await fs.writeFile(shimPath, `@echo off\r\n"${python}" %*\r\n`);
+        log.verbose('bin 垫片', `已创建 python3.cmd 指向 "${python}" 并加入 PATH`);
+      } else {
+        const symlinkDestination = path.join(buildBinsDir, 'python3');
+        try {
+          await fs.unlink(symlinkDestination);
+        } catch (err) {
+          if (err.code !== 'ENOENT') throw err;
         }
+        await fs.symlink(python, symlinkDestination);
+        log.verbose('bin 符号链接', `已在 "${buildBinsDir}" 创建指向 "${python}" 的符号链接并加入 PATH`);
       }
+    }
 
+    const proc = gyp.spawn(command, argv);
+    await new Promise((resolve, reject) => proc.on('exit', async (code, signal) => {
+      if (buildBinsDir) await fs.rm(buildBinsDir, { recursive: true }); // 清理构建期依赖的符号链接
+      if (code !== 0) return reject(new Error('`' + command + '` 执行失败,退出码: ' + code));
+      if (signal) return reject(new Error('`' + command + '` 收到信号: ' + signal));
+      resolve();
+    }))
+  },
+    /**
+     * 用 node-which 定位 msbuild / make 可执行文件
+     */
+    doWhich = async () => {
+      // Windows 使用 nodejs-mobile-gyp configure 提供的 msbuild
       if (win) {
-        // 用户是否指定了自己的 .sln 文件?
-        const hasSln = argv.some(arg => path.extname(arg) === '.sln');
-        if (!hasSln) argv.unshift(gyp.opts.solution || guessedSolution);
-      }
-
-      if (!win) {
-        // 把构建期依赖的符号链接(如 Python)加入 PATH
-        buildBinsDir = path.resolve('build', 'node_gyp_bins');
-        if (_hostIsWindows) {
-          const shellDir = findWindowsShellDir();
-          if (shellDir) {
-            process.env.PATH = `${shellDir};${process.env.PATH}`;
-            log.verbose('bin 环境', `已将 ${shellDir} 加入 PATH,供 make 使用`);
-          }
-          else log.warn('shell 环境', '未找到 sh.exe;GNU make 的 Unix 命令可能失败;建议安装 Git for Windows');
-        }
-        process.env.PATH = _hostIsWindows ? `${buildBinsDir};${process.env.PATH}` : `${buildBinsDir}:${process.env.PATH}`;
-        await fs.mkdir(buildBinsDir, { recursive: true });
-
-        if (_hostIsWindows) {
-          // Windows 无 python3 名称,且创建符号链接需要管理员权限;改用 .cmd 桥接
-          const shimPath = path.join(buildBinsDir, 'python3.cmd');
-          await fs.writeFile(shimPath, `@echo off\r\n"${python}" %*\r\n`);
-          log.verbose('bin 垫片', `已创建 python3.cmd 指向 "${python}" 并加入 PATH`);
-        } else {
-          const symlinkDestination = path.join(buildBinsDir, 'python3');
-          try {
-            await fs.unlink(symlinkDestination);
-          } catch (err) {
-            if (err.code !== 'ENOENT') throw err;
-          }
-          await fs.symlink(python, symlinkDestination);
-          log.verbose('bin 符号链接', `已在 "${buildBinsDir}" 创建指向 "${python}" 的符号链接并加入 PATH`);
-        }
+        if (!config.variables.msbuild_path) throw new Error('MSBuild 未设置,请先运行 `nodejs-mobile-gyp configure`');
+        command = config.variables.msbuild_path, log.verbose('使用 MSBuild:', command), await doBuild();
+        return;
       }
 
-      const proc = gyp.spawn(command, argv);
-      await new Promise((resolve, reject) => proc.on('exit', async (code, signal) => {
-        if (buildBinsDir) await fs.rm(buildBinsDir, { recursive: true }); // 清理构建期依赖的符号链接
-        if (code !== 0) return reject(new Error('`' + command + '` 执行失败,退出码: ' + code));
-        if (signal) return reject(new Error('`' + command + '` 收到信号: ' + signal));
-        resolve();
-      }))
+      // 先确认构建命令在 PATH 中
+      const execPath = await which(command);
+      log.verbose('`which` 成功解析 `' + command + '`', execPath), await doBuild();
     },
-      /**
-       * 用 node-which 定位 msbuild / make 可执行文件
-       */
-      doWhich = async () => {
-        // Windows 使用 nodejs-mobile-gyp configure 提供的 msbuild
-        if (win) {
-          if (!config.variables.msbuild_path) throw new Error('MSBuild 未设置,请先运行 `nodejs-mobile-gyp configure`');
-          command = config.variables.msbuild_path, log.verbose('使用 MSBuild:', command), await doBuild();
-          return;
-        }
-
-        // 先确认构建命令在 PATH 中
-        const execPath = await which(command);
-        log.verbose('`which` 成功解析 `' + command + '`', execPath), await doBuild();
-      },
-      /**
-       * Windows 下查找第一个 build/*.sln 文件
-       */
-      findSolutionFile = async () => {
-        const files = await glob('build/*.sln')
-        if (files.length === 0) throw new Error('未找到 *.sln 文件,是否运行过 configure?');
-        guessedSolution = files[0], log.verbose('找到首个解决方案文件', guessedSolution), await doWhich();
-      },
-      /**
-       * 加载 configure 阶段生成的 config.gypi
-       */
-      loadConfigGypi = async () => {
-        let data;
-        try {
-          const configPath = path.resolve('build', 'config.gypi');
-          data = await fs.readFile(configPath, 'utf8');
-        } catch (err) {
-          if (err.code === 'ENOENT') throw new Error('请先运行 `nodejs-mobile-gyp configure`');
-          else throw err;
-        }
+    /**
+     * Windows 下查找第一个 build/*.sln 文件
+     */
+    findSolutionFile = async () => {
+      const files = await glob('build/*.sln')
+      if (files.length === 0) throw new Error('未找到 *.sln 文件,是否运行过 configure?');
+      guessedSolution = files[0], log.verbose('找到首个解决方案文件', guessedSolution), await doWhich();
+    },
+    /**
+     * 加载 configure 阶段生成的 config.gypi
+     */
+    loadConfigGypi = async () => {
+      let data;
+      try {
+        const configPath = path.resolve('build', 'config.gypi');
+        data = await fs.readFile(configPath, 'utf8');
+      } catch (err) {
+        if (err.code === 'ENOENT') throw new Error('请先运行 `nodejs-mobile-gyp configure`');
+        else throw err;
+      }
 
-        // 从 config 中取出 arch、buildType、nodeDir
-        config = JSON.parse(data.replace(/#.+\n/, '')), buildType = config.target_defaults.default_configuration;
-        arch = config.variables.target_arch, nodeDir = config.variables.nodedir, python = config.variables.python;
+      // 从 config 中取出 arch、buildType、nodeDir
+      config = JSON.parse(data.replace(/#.+\n/, '')), buildType = config.target_defaults.default_configuration;
+      arch = config.variables.target_arch, nodeDir = config.variables.nodedir, python = config.variables.python;
 
-        if ('debug' in gyp.opts) buildType = gyp.opts.debug ? 'Debug' : 'Release';
-        if (!buildType) buildType = 'Release';
+      if ('debug' in gyp.opts) buildType = gyp.opts.debug ? 'Debug' : 'Release';
+      if (!buildType) buildType = 'Release';
 
-        log.verbose('构建类型', buildType), log.verbose('架构', arch), log.verbose('node 开发目录', nodeDir);
-        log.verbose('Python', python);
+      log.verbose('构建类型', buildType), log.verbose('架构', arch), log.verbose('node 开发目录', nodeDir);
+      log.verbose('Python', python);
 
-        win ? await findSolutionFile() : await doWhich();
-      };
-    await loadConfigGypi();
-  };
+      win ? await findSolutionFile() : await doWhich();
+    };
+  await loadConfigGypi();
+};
 
 build.usage = '调用 `' + (win ? 'msbuild' : 'make') + '` 构建模块';
 export { build };

package/lib/clean.js

@@ -1,16 +1,19 @@
 import gracefulFs from 'graceful-fs';
 import * as log from './log.js';
 
-const fs = gracefulFs.promises,
-  /**
-   * 清理:删除 build 目录
-   */
-  clean = async (gyp, argv) => {
-    const buildDir = 'build';
+/**
+ * 清理:删除 build 目录
+ * >查看定义:@see {@link clean}
+ * @param {object} gyp gyp 实例
+ * @param {string[]} argv 命令行参数
+ * @returns {Promise<void>}
+ */
+const clean = async (gyp, argv) => {
+  const buildDir = 'build';
 
-    log.verbose('清理', '正在删除 "%s" 目录', buildDir);
-    await fs.rm(buildDir, { recursive: true, force: true });
-  }
+  log.verbose('清理', '正在删除 "%s" 目录', buildDir);
+  await gracefulFs.promises.rm(buildDir, { recursive: true, force: true });
+};
 
 clean.usage = '删除生成的构建文件与 "out" 目录';
 export { clean };

package/lib/configure.js

@@ -1,14 +1,14 @@
 import gracefulFs from 'graceful-fs';
+import os from 'os';
 import path from 'path';
+import { format as msgFormat } from 'util';
+import { fileURLToPath } from 'url';
+import { createConfigGypi } from './create-config-gypi.js';
+import { findNodeDirectory } from './find-node-directory.js';
+import { PythonFinder } from './find-python.js';
 import * as log from './log.js';
-import os from 'os';
 import { processRelease } from './process-release.js';
-import { findNodeDirectory } from './find-node-directory.js';
-import { createConfigGypi } from './create-config-gypi.js';
-import { format as msgFormat } from 'util';
 import { findAccessibleSync } from './util.js';
-import { PythonFinder } from './find-python.js';
-import { fileURLToPath } from 'url';
 
 const fs = gracefulFs.promises, win = process.platform === 'win32',
     __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -22,6 +22,10 @@ if (win) {
 
 /**
  * 生成构建文件(Makefile / MSVC 工程)
+ * >查看定义:@see {@link configure}
+ * @param {object} gyp gyp 实例
+ * @param {string[]} argv 命令行参数
+ * @returns {Promise<void>}
  */
 const configure = async (gyp, argv) => {
   const buildDir = path.resolve('build'), configNames = ['config.gypi', 'common.gypi'], configs = [],