kkpack 0.1.0__py3-none-any.whl

kkpack/__init__.py

@@ -0,0 +1,21 @@
+"""kkpack —— 把 Python 项目打包成自带解释器的 exe，第三方依赖在首次运行时自动安装。
+
+设计要点：
+    * 用户的 requests / numpy 这类第三方库不进 exe，exe 只带 Python 运行时和
+      用户自己的代码；第三方依赖在目标机首次启动时按 requirements.txt 安装。
+    * 目标机既不需要 Python，也不需要 pip。
+    * kkpack 自身零第三方依赖。
+
+命令行：
+    kkpack main.py
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["main", "__version__"]
+
+
+def main(argv=None):
+    from .cli import main as _main
+
+    return _main(argv)

kkpack/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

kkpack/analyze.py

@@ -0,0 +1,232 @@
+"""源码分析：自动找出"开发者自己写的代码"，使发起人不必手写打包清单。
+
+kkpack 不需要用户声明要打包哪些模块 —— 后端（Nuitka / PyInstaller）本来就会
+顺着 import 语句往下追。真正的问题是**追不到的部分**：
+
+    1. importlib.import_module("xxx") / __import__() 这类动态导入
+    2. 插件注册表：程序只在运行期才知道要加载哪个模块
+
+本模块用 AST 把这些情况一并识别出来，产出显式的 include 清单交给后端，
+从而兑现"读源码就能把开发者所有自有代码打包进去"。
+
+同时对入口文件做体检，决定用哪种注入方式（见 bootgen）。
+"""
+
+import ast
+import os
+
+SKIP_DIRS = {
+    ".git", ".hg", ".svn", ".idea", ".vscode", "__pycache__", ".mypy_cache",
+    ".pytest_cache", ".tox", "node_modules", "site-packages", "venv", ".venv",
+    "env", "build", "dist", ".deps_build", ".kkpack", "wheels", "offline",
+}
+
+def iter_project_modules(root):
+    """遍历项目目录，返回 {模块名: 绝对路径}。
+
+    目录里的每一个 .py 都被登记 —— 包（含 __init__.py）记为包名，
+    单文件模块记为模块名。虚拟环境、hidden 目录、构建产物目录一律跳过。
+    """
+    modules = {}
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames
+                       if d not in SKIP_DIRS and not d.startswith(".")]
+        for name in filenames:
+            if not name.endswith(".py"):
+                continue
+            full = os.path.join(dirpath, name)
+            rel = os.path.relpath(full, root)
+            parts = rel[:-3].split(os.sep)
+            if not parts:
+                continue
+            if parts[-1] == "__init__":
+                parts = parts[:-1]
+                if not parts:
+                    continue
+            dotted = ".".join(parts)
+            modules.setdefault(dotted, full)
+    return modules
+
+
+_STDLIB_NAMES = None
+
+
+def _stdlib_names():
+    """标准库模块名集合。
+
+    ``sys.stdlib_module_names`` 是 3.10 才引入的；kkpack 声明支持 3.8+，
+    在 3.9 上它会退化成空集，于是 ``importlib.import_module("json")`` 被误报成
+    "动态导入未解析到本地文件"。这里补一个按标准库目录扫描的兜底。
+
+    方向上是安全的：这个集合只用来**抑制误报**，多收不会让任何东西被错误打包。
+    """
+    global _STDLIB_NAMES
+    if _STDLIB_NAMES is not None:
+        return _STDLIB_NAMES
+    import sys
+
+    names = set(getattr(sys, "stdlib_module_names", ()) or ())
+    names |= set(getattr(sys, "builtin_module_names", ()) or ())
+    lib = None
+    try:
+        import sysconfig
+
+        lib = sysconfig.get_paths().get("stdlib")
+    except Exception:  # noqa: BLE001
+        lib = None
+    lib = lib or os.path.dirname(os.__file__)
+    try:
+        for entry in os.listdir(lib):
+            if entry.endswith(".py"):
+                stem = entry[:-3]
+                if stem.isidentifier():
+                    names.add(stem)
+            elif entry.isidentifier():
+                names.add(entry)          # 包目录 / 扩展模块
+    except OSError:
+        pass
+    _STDLIB_NAMES = frozenset(names)
+    return _STDLIB_NAMES
+
+
+def scan_single_module(path):
+    """扫描单个文件的 import，返回 (静态导入名集合, 相对层级集合, 动态导入名集合)。"""
+    static, relative, dynamic = set(), set(), set()
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            source = fh.read()
+        tree = ast.parse(source)
+    except (OSError, SyntaxError, ValueError):
+        return static, relative, dynamic
+
+    def literal_str(node):
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            return node.value
+        return None
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                static.add(alias.name)
+        elif isinstance(node, ast.ImportFrom):
+            if node.level:                      # from . import x
+                relative.add(node.level)
+            if not node.module:
+                continue
+            static.add(node.module)
+            if node.level:
+                # 相对导入补不出完整点分路径，交给祖先包登记那一步处理
+                continue
+            # `from pkg import sub`：sub 很可能是**子模块**而不是属性。
+            # 不登记的话，没有 __init__.py 的目录结构（命名空间包）会整块漏掉 ——
+            # "pkg" 本身不是文件，闭包断在这里，目标机上直接 ImportError。
+            for alias in node.names:
+                if alias.name != "*":
+                    static.add("%s.%s" % (node.module, alias.name))
+        elif isinstance(node, ast.Call):
+            func = node.func
+            dotted = None
+            if isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
+                dotted = "%s.%s" % (func.value.id, func.attr)
+            elif isinstance(func, ast.Name):
+                dotted = func.id
+            if dotted in ("importlib.import_module", "__import__",
+                          "importlib.util.find_spec", "pkgutil.iter_modules"):
+                if dotted != "pkgutil.iter_modules" and node.args:
+                    name = literal_str(node.args[0])
+                    if name:
+                        dynamic.add(name)
+    return static, relative, dynamic
+
+
+def collect_local_modules(entry, root):
+    """从入口文件出发做闭包扫描，返回 (本地模块名集合, 动态导入且未解析到的名字)。"""
+    modules = iter_project_modules(root)
+    entry_rel = os.path.relpath(os.path.abspath(entry), root)
+    entry_mod = entry_rel[:-3].replace(os.sep, ".")
+    if entry_mod.endswith(".__init__"):
+        entry_mod = entry_mod[: -len(".__init__")]
+
+    local, unresolved = set(), set()
+    queue = [entry_mod]
+    seen = set()
+    while queue:
+        current = queue.pop()
+        if current in seen:
+            continue
+        seen.add(current)
+        path = modules.get(current)
+        if path is None:
+            continue
+        local.add(current)
+        # 连同祖先包一起登记：顶级包会用 --include-package 收拢整棵子树，
+        # 既不用逐个列举子模块，也覆盖了运行期才知道名字的动态子导入
+        parts = current.split(".")
+        for size in range(1, len(parts)):
+            ancestor = ".".join(parts[:size])
+            if ancestor in modules:
+                local.add(ancestor)
+                queue.append(ancestor)
+        static, _rel, dynamic = scan_single_module(path)
+        for name in list(static) + list(dynamic):
+            parts = name.split(".")
+            for size in range(len(parts), 0, -1):
+                candidate = ".".join(parts[:size])
+                if candidate in modules:
+                    queue.append(candidate)
+                    break
+            else:
+                if name in dynamic and parts[0] not in _stdlib_names():
+                    unresolved.add(name)
+    return local, unresolved
+
+
+def split_packages_and_modules(root, names):
+    """区分包与单模块：后端对两者用的参数不同（Nuitka 尤甚）。
+
+    包要用 --include-package 才会把子模块一并收进去，只给 --include-module
+    会得到"只有 __init__.py 被打包"的结果。
+    """
+    pkgs, mods = [], []
+    for name in sorted(names):
+        parts = name.split(".")
+        # 包 = 目录里有 __init__.py。这种必须交给 --include-package，
+        # 只给 --include-module 会得到"只有 __init__.py 被打包"的结果。
+        if os.path.exists(os.path.join(root, *parts, "__init__.py")):
+            pkgs.append(parts[0])
+        else:
+            mods.append(name)
+    pkgs = sorted(set(pkgs))
+    mods = sorted(set(m for m in mods if m.split(".")[0] not in pkgs))
+    return pkgs, mods
+
+
+def inspect_entry(entry):
+    """给入口文件做体检，决定用哪种方式注入运行期逻辑。
+
+    返回 dict:
+        relative : 是否含相对导入（from . import x）—— 这种文件不能被内联到
+                   顶层执行，必须走"模块模式"
+        sentinel : 是否有 if __name__ == "__main__" 守卫
+        syntax_ok: 语法是否可被解析
+    """
+    info = {"relative": False, "sentinel": False, "syntax_ok": True}
+    try:
+        with open(entry, "r", encoding="utf-8") as fh:
+            source = fh.read()
+        tree = ast.parse(source)
+    except (OSError, SyntaxError, ValueError) as exc:
+        info["syntax_ok"] = False
+        info["error"] = str(exc)
+        return info
+
+    sentinel, relative = False, False
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.level:
+            relative = True
+        if isinstance(node, ast.If):
+            left = getattr(node.test, "left", None)
+            if isinstance(left, ast.Name) and left.id == "__name__":
+                sentinel = True
+    info["relative"], info["sentinel"] = relative, sentinel
+    return info

kkpack/backends.py

@@ -0,0 +1,396 @@
+"""后端命令构造：Nuitka / PyInstaller。
+
+这里集中了几个"只有真跑过才知道"的关键参数，注释里都写了原因。
+"""
+
+import ast
+import os
+import sys
+
+from . import peinfo
+
+# 原则是"标准库一律打进 exe"：tkinter / turtle / sqlite3 / asyncio 全部在内。
+# 下面这些是唯一仍在排除之列的 —— 要么会让 Nuitka 编译期内部崩溃，要么纯粹是
+# 开发工具，进去只有体积代价没有收益。注意 lib2to3 之所以保留在列表里，
+# 是因为它依赖 test.support，而 test.support 在多条 Nuitka 版本上都有崩溃记录。
+SKIP_STDLIB = {
+    "test", "tests", "lib2to3", "__pycache__", "site-packages", "antigravity",
+    "ensurepip", "venv",
+}
+
+# 平台相关：Windows 的 CPython 里有 curses 源码但没有底层 _curses 扩展，
+# 强行 include 只会得到一条"无法处理"的错误。
+SKIP_STDLIB_WIN32 = {"curses"}
+
+
+def _skip_set():
+    names = set(SKIP_STDLIB)
+    if sys.platform == "win32":
+        names |= SKIP_STDLIB_WIN32
+    return names
+
+# AST 抓不到的动态 import / C 扩展的间接依赖，缺一个就连环崩，这里兜底。
+FALLBACK_STDLIB = {
+    "abc", "argparse", "base64", "binascii", "bisect", "bz2", "calendar", "cmath",
+    "codecs", "collections", "concurrent", "configparser", "contextlib", "copy",
+    "copyreg", "csv", "ctypes", "dataclasses", "datetime", "decimal", "difflib",
+    "email", "encodings", "enum", "errno", "fnmatch", "fractions", "functools",
+    "getopt", "getpass", "gettext", "glob", "gzip", "hashlib", "heapq", "hmac",
+    "html", "http", "importlib", "inspect", "io", "ipaddress", "itertools", "json",
+    "linecache", "locale", "logging", "lzma", "math", "mimetypes", "mmap", "netrc",
+    "numbers", "operator", "os", "pathlib", "pickle", "pkgutil", "platform", "pprint",
+    "queue", "random", "re", "secrets", "select", "selectors", "shlex", "shutil",
+    # 注意：不要放 sqlite3 —— 它会把 sqlite3.test / test.support 拖进来，
+    # 某些 Nuitka 版本编译 test.support 时会内部崩溃
+    "signal", "socket", "socketserver", "ssl", "stat", "statistics",
+    "string", "struct", "subprocess", "sysconfig", "tarfile", "tempfile", "textwrap",
+    "threading", "time", "tokenize", "traceback", "types", "typing", "unicodedata",
+    "urllib", "uuid", "warnings", "weakref", "xml", "zipfile", "zlib",
+}
+
+
+def stdlib_names():
+    lib = os.path.dirname(os.__file__)
+    skip = _skip_set()
+    # built-in 名字也收进来：AST 扫描时要能把 `import time` 认成标准库。
+    # 但真正发给后端的列表会在 split_mods_pkgs 里把纯 built-in 摘掉 —— 它们
+    # 没有文件可 include，且旧版 Nuitka 收到就崩（见 split_mods_pkgs 注释）
+    names = set(sys.builtin_module_names)
+    for entry in os.listdir(lib):
+        if entry.endswith(".py"):
+            name = entry[:-3]
+            # 必须先去掉扩展名再比 skip —— 拿 "antigravity.py" 去比 "antigravity"
+            # 永远不命中，skip 名单对单文件模块整体失效
+            if name in skip:
+                continue
+            if name.isidentifier():  # 排除 __phello__.foo 这类非法模块名的文件
+                names.add(name)
+            continue
+        if entry in skip:
+            continue
+        if entry.isidentifier() and os.path.exists(os.path.join(lib, entry, "__init__.py")):
+            names.add(entry)
+    return names
+
+
+def stdlib_test_submodules():
+    """标准库里所有 <pkg>.test 子包。
+
+    全量包含标准库时必须显式排除它们：sqlite3.test / unittest.test 会引入
+    test.support，而多个 Nuitka 版本编译 test.support 时都有内部崩溃记录。
+    """
+    lib = os.path.dirname(os.__file__)
+    out = []
+    for entry in sorted(os.listdir(lib)):
+        if entry in _skip_set():
+            continue
+        pkg_dir = os.path.join(lib, entry)
+        if os.path.isdir(pkg_dir) and os.path.exists(
+                os.path.join(pkg_dir, "test", "__init__.py")):
+            out.append("%s.test" % entry)
+    return out
+
+
+def is_builtin_or_frozen(name):
+    """这个名字是不是由解释器本体提供（built-in 或 frozen），即没有文件可 include。
+
+    判据与 Nuitka 自己的 `isBuiltinModuleName()` 同源：
+
+        _imp.is_builtin(name) or _imp.is_frozen(name)
+
+    为什么不能只看"Lib 里有没有 <name>.py"：CPython 3.9 上 **zipimport 是
+    frozen 模块**，`Lib/zipimport.py` 确实躺在磁盘上，但解释器用的是冻结版 ——
+    Nuitka 照样把它判成 built-in（日志原文："Note, module 'zipimport' that you
+    asked to include is built-in."）。按"有没有文件"筛会把它漏过去，旧版
+    Nuitka 依然崩。
+    """
+    try:
+        import _imp
+    except ImportError:  # pragma: no cover - CPython 一定有
+        return name in sys.builtin_module_names
+
+    mk_is_builtin = getattr(_imp, "is_builtin", None)
+    mk_is_frozen = getattr(_imp, "is_frozen", None)
+    if mk_is_builtin is None or mk_is_frozen is None:  # pragma: no cover
+        return name in sys.builtin_module_names
+
+    return bool(mk_is_builtin(name)) or bool(mk_is_frozen(name))
+
+
+def builtin_modules(names=None):
+    """候选名单里由解释器本体提供的模块（built-in + frozen）。
+
+    给它们发 `--include-module` 不但没意义（本来就编在解释器里），
+    还会让旧版 Nuitka 在解析 include 列表时内部崩溃。
+
+    不传 `names` 就按全量标准库名统计，用于报数：Python 3.9 上是 68 个
+    （67 个 `sys.builtin_module_names` + frozen 的 zipimport）。
+    """
+    if names is None:
+        names = stdlib_names()
+    return {name for name in names if is_builtin_or_frozen(name)}
+
+
+def split_mods_pkgs(names):
+    """区分单模块与包：两者对后端要用不同的参数，混用会漏掉子模块。
+
+    顺带把 built-in / frozen 模块（_abc / _winapi / sys / time / zlib / zipimport …）
+    摘掉：它们由解释器本体提供，没有可 include 的文件。
+    而 Nuitka 2.3.2 收到 `--include-module=<built-in>` 会在解析 include 列表时
+    直接内部崩溃：
+
+        Recursion.checkPluginSinglePath(plugin_filename=None)
+        -> os.path.abspath(None)
+        -> TypeError: _getfullpathname: path should be string, bytes or
+           os.PathLike, not NoneType
+
+    Nuitka 2.7.13 起才加了 module_kind == "built-in" 的判断，改成只警告
+    "Note, module X that you asked to include is built-in."。所以想在旧 Nuitka
+    上也能打包，就必须在构造参数前把它们摘掉（摘掉后产物完全不变，
+    built-in 本来就在解释器里）。
+    """
+    skip = _skip_set()
+    lib = os.path.dirname(os.__file__)
+    builtin = builtin_modules(names)
+    mods, pkgs = [], []
+    for name in sorted(names):
+        if name in skip:
+            continue
+        pkg_dir = os.path.join(lib, name)
+        if os.path.isdir(pkg_dir) and os.path.exists(os.path.join(pkg_dir, "__init__.py")):
+            pkgs.append(name)
+            continue
+        if name in builtin:
+            continue
+        mods.append(name)
+    return mods, pkgs
+
+
+def ast_stdlib_modules(wheels_dir, wheel_files):
+    """精确模式：AST 扫描"运行时才装"的 wheel，只收它们真正 import 的标准库模块。
+
+    为什么必须做这件事：第三方库被 --nofollow-import-to 排除后，后端就看不见它们
+    import 的标准库模块了。实测 requests 会缺 hmac、urllib3 会缺 http.cookies，
+    补一个又冒出下一个 —— 连锁崩溃。
+    """
+    known = stdlib_names()
+    found = set()
+    for filename in wheel_files:
+        path = os.path.join(wheels_dir, filename)
+        try:
+            import zipfile
+
+            with zipfile.ZipFile(path) as zf:
+                names = [n for n in zf.namelist() if n.endswith(".py")]
+                sources = [(n, zf.read(n)) for n in names]
+        except Exception:  # noqa: BLE001
+            continue
+        for _name, raw in sources:
+            try:
+                tree = ast.parse(raw)
+            except (SyntaxError, ValueError):
+                continue
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Import):
+                    for alias in node.names:
+                        top = alias.name.split(".")[0]
+                        if top in known:
+                            found.add(top)
+                elif isinstance(node, ast.ImportFrom) and node.module and not node.level:
+                    top = node.module.split(".")[0]
+                    if top in known:
+                        found.add(top)
+    return found
+
+
+def stdlib_targets(cfg, wheels_dir, wheel_files):
+    mode = cfg["stdlib_mode"]
+    if mode == "none":
+        return [], []
+    if mode == "full":
+        return split_mods_pkgs(stdlib_names())
+    scanned = ast_stdlib_modules(wheels_dir, wheel_files)
+    total = scanned | FALLBACK_STDLIB | set(cfg["stdlib_extra"])
+    return split_mods_pkgs(total)
+
+
+def non_ascii_build_paths(ctx):
+    """构建路径里含非 ASCII 字符的那些（中文目录）。
+
+    这类路径会让 ccache 的日志变成非 UTF-8：ccache 是原生程序，日志按系统
+    ANSI 代码页写（中文 Windows = GBK），而 Nuitka 2.3.2 用 UTF-8 读它
+    （`build/SconsCaching._getCcacheStatistics`），于是**编译成功之后**在收尾
+    统计时崩：
+
+        UnicodeDecodeError: 'utf-8' codec can't decode byte 0xd7 ...
+
+    实测 `D:\\桌面文件夹\\...` 必现（日志里原样写着这个路径的 GBK 字节）。
+    """
+    candidates = [
+        ctx.get("project_root"), ctx.get("entry_path"),
+        ctx["cfg"].get("output_dir"), sys.prefix,
+        getattr(sys, "base_prefix", None),
+    ]
+    return [p for p in candidates if p and any(ord(ch) > 127 for ch in p)]
+
+
+def python3_dll():
+    """构建机上 CPython 稳定 ABI 转发 DLL（`python3.dll`）的绝对路径；没有则 None。
+
+    为什么必须随产物带过去：
+    Windows 上 abi3 轮子（PySide6 / shiboken6 都是 `cp39-abi3`）的扩展链接的是
+    **`python3.dll`**（版本无关的转发层），而不是 `python39.dll`。这类包被
+    `--nofollow-import-to` 排除在编译之外、改成运行时安装，后端因此根本看不到
+    它们的 DLL 依赖，也就不会把 `python3.dll` 收进产物；而目标机上没有 Python，
+    更不会凭空出现这个文件。实测症状：
+
+        ImportError: DLL load failed while importing Shiboken: 找不到指定的模块。
+
+    读 PE 导入表可确认：`shiboken6/Shiboken.pyd` 与 `shiboken6/shiboken6.abi3.dll`
+    的导入表里都写着 `python3.dll`。把文件补到 exe 同级后窗口即正常显示。
+
+    位置在 Python 安装根目录（venv 里则在 base 前缀），`sys.base_prefix` 优先。
+    """
+    if sys.platform != "win32":
+        return None
+    for base in (getattr(sys, "base_prefix", None), sys.prefix):
+        if not base:
+            continue
+        candidate = os.path.join(base, "python3.dll")
+        if os.path.isfile(candidate):
+            return candidate
+    return None
+
+
+def nuitka_cmd(ctx):
+    """Nuitka 命令。
+
+    console=False 时必须加 --windows-disable-console：Nuitka 默认继承控制台子系统，
+    GUI 程序跑起来会先闪一个黑窗口，且关不掉。
+    """
+    cfg = ctx["cfg"]
+    cmd = [
+        ctx["python"], "-m", "nuitka",
+        "--onefile" if cfg["onefile"] else "--standalone",
+    ]
+    if not cfg.get("console", True) and sys.platform == "win32":
+        # GUI 模式：没有黑窗口后 print 全部不可见，首次安装依赖的反馈
+        # 只能靠运行期的 tkinter 进度条，别把它也关了
+        cmd.append("--windows-disable-console")
+    # 不加这个，_tkinter.pyd 虽然编进去了，import tkinter 依然报
+    # "Need to use '--enable-plugin=tk-inter'"，进度条和用户的 GUI 都废了
+    if cfg.get("tkinter", True) and cfg["stdlib_mode"] != "none":
+        cmd.append("--enable-plugin=tk-inter")
+    icon = ctx.get("icon")
+    if icon and sys.platform == "win32":
+        cmd.append("--windows-icon-from-ico=%s" % icon)
+    # 版本资源：没有公司名 / 版本号的未签名 exe 是安全软件的重点怀疑对象。
+    # Nuitka 不写这一栏（--product-name 的帮助里那句"Defaults to base filename"
+    # 只在给了字符串时才生效），所以要显式传，见 peinfo 模块注释
+    cmd += peinfo.nuitka_flags(ctx.get("version_info"))
+    dll = python3_dll()
+    if dll:
+        # abi3 轮子（PySide6 / shiboken6）要它才能加载，见 python3_dll() 注释
+        cmd.append("--include-data-files=%s=python3.dll" % dll)
+    if non_ascii_build_paths(ctx):
+        # 中文路径下 ccache 会写出非 UTF-8 日志，Nuitka 收尾统计时崩
+        # —— 关掉它就没有 CCACHE_LOGFILE，那段逻辑整块跳过（见函数注释）
+        cmd.append("--disable-ccache")
+    cmd += [
+        "--mingw64" if ctx["compiler"] == "mingw64" else "--msvc=latest",
+        "--assume-yes-for-downloads",
+        "--jobs=%d" % cfg["jobs"],     # 限制并行，降低 C 编译峰值内存
+        # LTO 必须关：include 模块变多后，链接阶段会爆内存而中途被杀
+        "--lto=%s" % ("yes" if cfg["lto"] else "no"),
+        # 别把 unittest / setuptools / pytest 那一坨拖进来：既拖慢编译，
+        # 也容易触发 Nuitka 内部崩溃
+        "--noinclude-unittest-mode=nofollow",
+        "--noinclude-setuptools-mode=nofollow",
+        "--noinclude-pytest-mode=nofollow",
+        "--include-module=%s" % ctx["manifest_module"],
+        "--include-module=%s" % ctx["runtime_module"],
+        "--output-dir=%s" % cfg["output_dir"],
+    ]
+    body_mod = ctx.get("entry_body_module")
+    if body_mod:
+        cmd.append("--include-module=%s" % body_mod)
+    for pkg in ctx["local_packages"]:
+        cmd.append("--include-package=%s" % pkg)   # 包必须这样收，否则只有 __init__.py
+    for mod in ctx["local_modules"]:
+        cmd.append("--include-module=%s" % mod)
+    if cfg["stdlib_mode"] != "none":
+        mods, pkgs = ctx["stdlib_targets"]
+        cmd += ["--include-module=%s" % m for m in mods]
+        cmd += ["--include-package=%s" % p for p in pkgs]
+        cmd += ["--nofollow-import-to=%s" % t for t in ctx.get("stdlib_tests", [])]
+    for mod in sorted(ctx["bundled_modules"]):
+        cmd.append("--include-package=%s" % mod)
+    for mod in sorted(ctx["runtime_modules"]):
+        cmd.append("--nofollow-import-to=%s" % mod)
+    cmd.append(ctx["entry_path"])
+    # 后端产物名由主模块名决定，用 module_stem；用户要的产物名在编译后改名
+    stem = ctx.get("module_stem") or ctx["stem"]
+    if cfg["onefile"]:
+        artifact = os.path.join(cfg["output_dir"], stem + ".exe")
+    else:
+        artifact = os.path.join(cfg["output_dir"], stem + ".dist", stem + ".exe")
+    return cmd, artifact
+
+
+def pyinstaller_cmd(ctx):
+    cfg = ctx["cfg"]
+    cmd = [
+        ctx["python"], "-m", "PyInstaller",
+        "--onefile" if cfg["onefile"] else "--onedir",
+    ]
+    # PyInstaller 的 --noconsole 只在 Windows / macOS 有意义，Linux 上会被拒绝
+    if not cfg.get("console", True) and sys.platform in ("win32", "darwin"):
+        cmd.append("--noconsole")
+    icon = ctx.get("icon")
+    if icon and sys.platform == "win32":
+        cmd.append("--icon=%s" % icon)
+    # 版本资源走一个文件：PyInstaller 只认 --version-file 里的 VSVersionInfo 结构
+    version_file = ctx.get("version_file")
+    if version_file and sys.platform == "win32":
+        cmd.append("--version-file=%s" % version_file)
+    dll = python3_dll()
+    if dll:
+        # 同上：目标机上没有 Python，abi3 扩展靠它才能加载
+        cmd.append("--add-data=%s%s." % (dll, os.pathsep))
+    cmd += [
+        "--noconfirm", "--clean",
+        "--distpath", os.path.join(cfg["output_dir"], "dist"),
+        "--workpath", os.path.join(cfg["output_dir"], "build"),
+        "--specpath", cfg["output_dir"],
+        "--hidden-import=%s" % ctx["manifest_module"],
+        "--hidden-import=%s" % ctx["runtime_module"],
+    ]
+    body_mod = ctx.get("entry_body_module")
+    if body_mod:
+        cmd.append("--hidden-import=%s" % body_mod)
+    if ctx["bundled_files"]:
+        cmd += ["--paths", ctx["deps_build"]]
+    for mod in ctx["local_modules"]:
+        cmd.append("--hidden-import=%s" % mod)
+    for pkg in ctx["local_packages"]:
+        # 必须用 collect-submodules：--hidden-import 只收包本身，
+        # 不递归子模块，于是很容易挂在没被打包的子模块上
+        cmd.append("--collect-submodules=%s" % pkg)
+    if cfg["stdlib_mode"] != "none":
+        mods, pkgs = ctx["stdlib_targets"]
+        cmd += ["--hidden-import=%s" % m for m in mods]
+        cmd += ["--collect-submodules=%s" % p for p in pkgs]
+        # 和 Nuitka 一样必须挡住 <pkg>.test：sqlite3.test -> test.support
+        # 是已知会把打包器拖崩/拖胖的组合
+        cmd += ["--exclude-module=%s" % t for t in ctx.get("stdlib_tests", [])]
+    for mod in sorted(ctx["bundled_modules"]):
+        cmd.append("--collect-submodules=%s" % mod)
+    for mod in sorted(ctx["runtime_modules"]):
+        cmd.append("--exclude-module=%s" % mod)
+    cmd.append(ctx["entry_path"])
+    stem = ctx.get("module_stem") or ctx["stem"]
+    if cfg["onefile"]:
+        artifact = os.path.join(cfg["output_dir"], "dist", stem + ".exe")
+    else:
+        artifact = os.path.join(cfg["output_dir"], "dist", stem, stem + ".exe")
+    return cmd, artifact