crogram-pythub 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
pythub/exe_archive.py ADDED
@@ -0,0 +1,414 @@
1
+ """自研单文件打包器(P3 全平台化):bootloader(自研 C 引导器)+ 自研归档格式 v2。
2
+
3
+ 同一套 C 引导器源码 + 归档格式,三平台产出:
4
+ - Windows : PE (.exe) —— mingw 交叉编译(-mconsole / -mwindows)
5
+ - macOS : Mach-O (.nexe) —— 本机 cc 编译 POSIX 分支
6
+ - Linux : ELF (.nexe) —— 本机 cc 编译 POSIX 分支
7
+
8
+ 参考 PyInstaller CArchive/bootloader 的思路独立实现,全程不依赖 PyInstaller:
9
+
10
+ - 归档格式 v2(见 bootloader/bootex.c 头部注释):
11
+ [ 引导器本体 ][ 文件数据区 ][ TOC ][ 96 字节 cookie ]
12
+ 每条目可选 zlib(DEFLATE) 压缩(Python 端 zlib.compress 压缩,C 端内嵌
13
+ miniz/tinfl 解压);cookie 含魔数、偏移、(数据区+TOC) 的 MD5(缓存键)
14
+ 与应用名(缓存按应用分组清理)。
15
+
16
+ - 引导器: 自研 C 源码随包分发(bootloader/bootex.c + vendored miniz tinfl
17
+ 解压器,仅 1 个 .c + 3 个 .h),Windows 分支首次打包时用 mingw-w64 交叉
18
+ 编译 PE,POSIX 分支用本机 cc 编译 Mach-O/ELF,产物缓存到 PYTHUB_CACHE_DIR
19
+ ——构建机无需安装 Windows / MSVC / Visual Studio。
20
+
21
+ - stdlib zip 化(文件数骤减): runtime/Lib 的 .py 打成单个 stdlib.zip,
22
+ 配 pythonXY._pth 引导(官方 embeddable 同款机制),TOC 条目数从 ~1600
23
+ 降到 ~20,首次解压显著提速;site-packages 与非 .py 文件保持散文件。
24
+
25
+ - 完整性校验(P2): 运行时校验归档体 MD5(防单文件被篡改/截断)与缓存启动器
26
+ MD5(防缓存目录被篡改),不一致时自动重新解压。
27
+ - 窗口子系统(P2): pythub.toml [app] windowed=true 时编译 -mwindows PE,
28
+ GUI 应用不闪控制台黑框,致命错误用 MessageBox 呈现。
29
+ - 缓存清理(P2): cookie 携带应用名(归档格式 v3),运行时缓存按应用分组
30
+ (<缓存>/exe/<应用>/<md5>);引导器每次首次解压后 LRU 清理同应用旧 md5
31
+ 目录,并按缓存总大小上限(默认 4GB,可用 PYTHUB_CACHE_MAX_MB 覆盖)
32
+ 从最久未用的应用组开始驱逐。
33
+ """
34
+
35
+ from __future__ import annotations
36
+
37
+ import hashlib
38
+ import io
39
+ import os
40
+ import platform as _platform_mod
41
+ import shutil
42
+ import struct
43
+ import subprocess
44
+ import sys
45
+ import zipfile
46
+ import zlib
47
+ from pathlib import Path
48
+ from typing import List, Tuple
49
+
50
+ from pythub.utils import PYTHUB_CACHE_DIR, find_executable, set_executable
51
+
52
+ MAGIC = b"PYTHEX3\x00"
53
+ COOKIE_SIZE = 96
54
+ APP_FIELD_SIZE = 32
55
+ FLAG_DEFLATE = 1
56
+
57
+
58
+ def sanitize_app_name(name: str) -> str:
59
+ """应用名净化为缓存目录安全名: 仅 [A-Za-z0-9._-],其余替换为 _,截断 32 字节。
60
+
61
+ 该值写入 cookie 应用名字段,用作运行时缓存的分组目录名(LRU 清理的
62
+ "同一应用"识别键),无需保留原始大小写以外的语义。"""
63
+ cleaned = "".join(
64
+ c if (c.isascii() and (c.isalnum() or c in "._-")) else "_"
65
+ for c in (name or "")
66
+ )
67
+ cleaned = cleaned[:APP_FIELD_SIZE].lstrip(".") or "_app"
68
+ return cleaned
69
+
70
+ # TOC 条目: path_len(u32), stored_size(u32), raw_size(u32), offset(u64), flags(u8)
71
+ _TOC_ITEM_FMT = "<IIIQB"
72
+
73
+ FLAG_DEFLATE = 1 # 条目经 zlib 压缩
74
+ FLAG_SYMLINK = 2 # 条目为符号链接,内容为链接目标串(POSIX 重建;Windows 回退为普通文件)
75
+
76
+ _BOOT_SOURCES = ("bootex.c", "miniz_tinfl.c")
77
+ _CROSS_GCC = {
78
+ "x86_64": "x86_64-w64-mingw32-gcc",
79
+ "aarch64": "aarch64-w64-mingw32-gcc",
80
+ }
81
+ _COMPILE_BASE = ["-O2", "-s", "-Wall"]
82
+
83
+
84
+ def _compile_flags(console: bool) -> list:
85
+ """console=True 控制台子系统(默认); False 窗口子系统:
86
+ -mwindows 无控制台窗口,GUI_APP 下致命错误用 MessageBox 呈现、状态输出静默。"""
87
+ subsystem = ["-mconsole"] if console else ["-mwindows", "-DGUI_APP=1"]
88
+ return _COMPILE_BASE + subsystem + ["-lshell32"]
89
+
90
+
91
+ def _check_path(name: str) -> None:
92
+ """防路径穿越(与 bootex.c unsafe_path 同规则): 拒绝绝对路径、盘符、.. 段。"""
93
+ if not name:
94
+ raise ValueError("归档条目路径为空")
95
+ if name[0] in "/\\":
96
+ raise ValueError(f"归档条目为绝对路径: {name!r}")
97
+ if len(name) >= 2 and name[1] == ":" and name[0].isascii() and name[0].isalpha():
98
+ raise ValueError(f"归档条目含盘符: {name!r}")
99
+ for part in name.replace("\\", "/").split("/"):
100
+ if part == "..":
101
+ raise ValueError(f"归档条目含 .. 路径段: {name!r}")
102
+
103
+
104
+ def _bootloader_dir() -> Path:
105
+ return Path(__file__).parent / "bootloader"
106
+
107
+
108
+ def native_host_platform() -> Optional[str]:
109
+ """本机平台名(nexe 只能在本机对应平台上生成)。"""
110
+ if sys.platform == "darwin":
111
+ return "macos"
112
+ if sys.platform.startswith("linux"):
113
+ return "linux"
114
+ return None
115
+
116
+
117
+ def native_host_arch() -> str:
118
+ """本机架构(归一为 x86_64/aarch64)。"""
119
+ m = _platform_mod.machine()
120
+ return {"arm64": "aarch64"}.get(m, m)
121
+
122
+
123
+ def ensure_bootloader(arch: str = "x86_64", console: bool = True, logger=None) -> Path:
124
+ """交叉编译自研引导器并缓存(bootex + miniz 任一源码或编译标志变化自动重编译)。"""
125
+ if arch not in _CROSS_GCC:
126
+ raise ValueError(f"不支持的 Windows 架构: {arch}")
127
+ bdir = _bootloader_dir()
128
+ sources = [bdir / s for s in _BOOT_SOURCES]
129
+ for s in sources:
130
+ if not s.exists():
131
+ raise RuntimeError(f"引导器源码缺失: {s}")
132
+ flags = _compile_flags(console)
133
+ key = hashlib.md5(
134
+ b"".join(s.read_bytes() for s in sources) + repr(flags).encode()
135
+ ).hexdigest()[:12]
136
+ cache = PYTHUB_CACHE_DIR / "bootloader" / f"win-{arch}-{key}"
137
+ out = cache / "bootex.exe"
138
+ if out.exists():
139
+ return out
140
+
141
+ cc = find_executable(_CROSS_GCC[arch])
142
+ if not cc:
143
+ raise RuntimeError(
144
+ f"生成 .exe 需要交叉编译器 {_CROSS_GCC[arch]}(用于编译自研 PE 引导器)。\n"
145
+ "macOS: brew install mingw-w64 | Ubuntu: apt install gcc-mingw-w64-x86-64"
146
+ )
147
+ cache.mkdir(parents=True, exist_ok=True)
148
+ tmp_out = cache / f"bootex.tmp-{os.getpid()}"
149
+ proc = subprocess.run(
150
+ [cc, *flags, "-o", str(tmp_out), *[str(s) for s in sources]],
151
+ capture_output=True,
152
+ text=True,
153
+ )
154
+ if proc.returncode != 0:
155
+ shutil.rmtree(cache, ignore_errors=True) # 失败清理缓存目录(防半成品残留)
156
+ raise RuntimeError(f"引导器编译失败:\n{proc.stderr}")
157
+ os.replace(tmp_out, out) # 原子落位,并发构建安全
158
+ if logger:
159
+ logger.info("引导器编译完成: %s", out)
160
+ return out
161
+
162
+
163
+ def _stdlib_zipify(
164
+ entries: List[Tuple[str, bytes, bool]], python: str
165
+ ) -> List[Tuple[str, bytes, bool]]:
166
+ """stdlib zip 化: runtime/Lib 的 .py 合并为 runtime/stdlib.zip,
167
+ 并生成 pythonXY._pth(官方 embeddable 同款机制)引导解释器从 zip 导入。"""
168
+ lib_prefix = "runtime/Lib/"
169
+ lib_py = [e for e in entries if e[0].startswith(lib_prefix) and e[0].endswith(".py")]
170
+ if not lib_py:
171
+ return entries
172
+
173
+ loose: List[Tuple[str, bytes, bool]] = []
174
+ zip_items: List[Tuple[str, bytes]] = []
175
+ for rel, data, is_link in lib_py:
176
+ sub = rel[len(lib_prefix):]
177
+ if sub.startswith("site-packages/"):
178
+ loose.append((rel, data, is_link)) # 站内包保持散文件,路径语义不变
179
+ else:
180
+ zip_items.append((sub, data))
181
+
182
+ buf = io.BytesIO()
183
+ with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED, compresslevel=9) as zf:
184
+ for arc, data in sorted(zip_items):
185
+ zf.writestr(arc, data)
186
+
187
+ result = [e for e in entries if not (e[0].startswith(lib_prefix) and e[0].endswith(".py"))]
188
+ result += loose # site-packages .py 保持散文件
189
+ result.append(("runtime/stdlib.zip", buf.getvalue(), False))
190
+
191
+ # pythonXY._pth: 相对路径基于 runtime/(_pth 文件所在目录)
192
+ pth_name = f"runtime/python{python.replace('.', '')}._pth"
193
+ lines = ["stdlib.zip"]
194
+ if any(rel.startswith("runtime/DLLs/") for rel, _, _ in result):
195
+ lines.append("DLLs")
196
+ # Lib 行: 有 site-packages 散文件或任何 Lib/ 下非 .py 条目(如 .pyd)时必须保留
197
+ if loose or any(rel.startswith(lib_prefix) for rel, _, _ in result):
198
+ lines.append("Lib")
199
+ lines.append(".") # runtime 根(pythonXY.dll 等所在)
200
+ result.append((pth_name, ("\n".join(lines) + "\n").encode("ascii"), False))
201
+ return result
202
+
203
+
204
+ def _collect_entries(bundle_dir: Path) -> List[Tuple[str, bytes, bool]]:
205
+ """收集 bundle 全部条目为 (相对路径, 内容, 是否符号链接)。
206
+
207
+ 符号链接条目的"内容"为链接目标串(如 bin/python3 -> python3.12),
208
+ 归档中以 FLAG_SYMLINK 存储,引导器解压时重建(POSIX),避免跟随
209
+ symlink 复制整个目标文件(python3.12 二进制会被重复打包 ~15MB)。"""
210
+ entries: List[Tuple[str, bytes, bool]] = []
211
+ for root, dirs, fnames in os.walk(bundle_dir):
212
+ dirs.sort()
213
+ rel_root = Path(root).relative_to(bundle_dir)
214
+ for fn in sorted(fnames):
215
+ rel = (rel_root / fn).as_posix()
216
+ p = Path(root) / fn
217
+ if p.is_symlink():
218
+ entries.append((rel, os.readlink(p).encode("utf-8"), True))
219
+ else:
220
+ entries.append((rel, p.read_bytes(), False))
221
+ return entries
222
+
223
+
224
+ def _write_archive(
225
+ boot_bytes: bytes,
226
+ bundle_dir: Path,
227
+ out: Path,
228
+ python: str,
229
+ zipify: bool = True,
230
+ app_name: str = "",
231
+ ) -> Path:
232
+ """引导器 + 自研归档拼装(Windows exe 与原生 nexe 共用)。
233
+
234
+ app_name 写入 cookie 应用名字段(v3),引导器据此把运行时缓存分组到
235
+ <缓存>/exe/<应用>/<md5>,实现同应用旧 md5 目录 LRU 清理。"""
236
+ entries = _stdlib_zipify(_collect_entries(bundle_dir), python) if zipify \
237
+ else _collect_entries(bundle_dir)
238
+ entries.sort(key=lambda e: e[0])
239
+
240
+ payload_offset = len(boot_bytes)
241
+ blob = bytearray()
242
+ toc_items = []
243
+ for rel, data, is_link in entries:
244
+ off = payload_offset + len(blob)
245
+ comp = zlib.compress(data, 9)
246
+ if len(comp) < len(data):
247
+ stored, flags = comp, FLAG_DEFLATE
248
+ else:
249
+ stored, flags = data, 0
250
+ if is_link:
251
+ flags |= FLAG_SYMLINK
252
+ blob += stored
253
+ toc_items.append((rel, len(stored), len(data), off, flags))
254
+
255
+ toc = bytearray(struct.pack("<I", len(toc_items)))
256
+ for rel, stored, raw, off, flags in toc_items:
257
+ pb = rel.encode("utf-8")
258
+ toc += struct.pack(_TOC_ITEM_FMT, len(pb), stored, raw, off, flags)
259
+ toc += pb
260
+
261
+ toc_offset = payload_offset + len(blob)
262
+ md5 = hashlib.md5(bytes(blob) + bytes(toc)).hexdigest()
263
+ cookie = bytearray(MAGIC)
264
+ cookie += struct.pack("<QQQ", payload_offset, toc_offset, len(toc))
265
+ cookie += md5.encode("ascii").ljust(32, b"\0")
266
+ app_field = sanitize_app_name(app_name).encode("ascii").ljust(APP_FIELD_SIZE, b"\0")
267
+ assert len(app_field) == APP_FIELD_SIZE
268
+ cookie += app_field
269
+ assert len(cookie) == COOKIE_SIZE
270
+
271
+ out.parent.mkdir(parents=True, exist_ok=True)
272
+ tmp = out.with_name(f"{out.name}.tmp-{os.getpid()}")
273
+ try:
274
+ with open(tmp, "wb") as f:
275
+ f.write(boot_bytes)
276
+ f.write(bytes(blob))
277
+ f.write(bytes(toc))
278
+ f.write(bytes(cookie))
279
+ os.replace(tmp, out) # 原子落位:中断不会留下损坏的产物
280
+ finally:
281
+ if tmp.exists():
282
+ tmp.unlink(missing_ok=True)
283
+ set_executable(out)
284
+ return out
285
+
286
+
287
+ def make_exe(
288
+ bundle_dir: Path,
289
+ out: Path,
290
+ arch: str = "x86_64",
291
+ python: str = "3.12",
292
+ logger=None,
293
+ console: bool = True,
294
+ app_name: str = "",
295
+ ) -> Path:
296
+ """把自包含目录打包为单文件 Windows .exe(自研归档 + 自研 PE 引导器)。
297
+
298
+ - 条目按需 zlib 压缩(压缩无收益则原样存储);
299
+ - stdlib zip 化将 Lib/*.py 合并为单个 stdlib.zip,文件数骤减;
300
+ - console=False 生成窗口子系统 PE(GUI 应用不闪黑框);
301
+ - app_name 写入 cookie,运行时缓存按应用分组并 LRU 清理旧版本。
302
+ """
303
+ boot = ensure_bootloader(arch, console, logger)
304
+ return _write_archive(boot.read_bytes(), bundle_dir, out, python,
305
+ zipify=True, app_name=app_name)
306
+
307
+
308
+ def ensure_bootloader_native(console: bool = True, logger=None) -> Path:
309
+ """编译 POSIX 原生引导器(macOS Mach-O / Linux ELF)并缓存。
310
+
311
+ 引导器源码或编译标志变化自动重编译;仅本机平台(POSIX 分支用
312
+ /proc/self/exe 或 argv0 定位自身,两端共用一套源码)。"""
313
+ bdir = _bootloader_dir()
314
+ sources = [bdir / s for s in _BOOT_SOURCES]
315
+ for s in sources:
316
+ if not s.exists():
317
+ raise RuntimeError(f"引导器源码缺失: {s}")
318
+ flags = ["-O2", "-s"] + ([] if console else ["-DGUI_APP=1"])
319
+ key = hashlib.md5(
320
+ b"".join(s.read_bytes() for s in sources) + repr(flags).encode()
321
+ ).hexdigest()[:12]
322
+ cache = PYTHUB_CACHE_DIR / "bootloader" / f"native-{sys.platform}-{key}"
323
+ out = cache / "bootex"
324
+ if out.exists():
325
+ return out
326
+
327
+ cc = find_executable("cc") or find_executable("gcc") or find_executable("clang")
328
+ if not cc:
329
+ raise RuntimeError("需要 C 编译器 cc/gcc/clang(用于编译 POSIX 引导器)")
330
+ cache.mkdir(parents=True, exist_ok=True)
331
+ tmp_out = cache / f"bootex.tmp-{os.getpid()}"
332
+ proc = subprocess.run(
333
+ [cc, *flags, "-o", str(tmp_out), *[str(s) for s in sources]],
334
+ capture_output=True,
335
+ text=True,
336
+ )
337
+ if proc.returncode != 0:
338
+ shutil.rmtree(cache, ignore_errors=True)
339
+ raise RuntimeError(f"引导器编译失败:\n{proc.stderr}")
340
+ os.replace(tmp_out, out) # 原子落位,并发构建安全
341
+ if proc.stderr.strip() and logger:
342
+ logger.warning("引导器编译警告:\n%s", proc.stderr.strip())
343
+ return out
344
+
345
+
346
+ def make_native_exe(
347
+ bundle_dir: Path,
348
+ out: Path,
349
+ platform: str = "linux",
350
+ arch: Optional[str] = None,
351
+ python: str = "3.12",
352
+ logger=None,
353
+ console: bool = True,
354
+ app_name: str = "",
355
+ ) -> Path:
356
+ """单文件原生可执行(macOS Mach-O / Linux ELF),与 Windows exe 同款自研
357
+ 归档格式(PYTHEX3 + cookie + 双层完整性校验 + 原子解压 + 并发互斥)。
358
+
359
+ - 仅支持在本机对应平台上生成(编译器不做 POSIX 交叉);跨平台请用 run/
360
+ tar.gz 格式;
361
+ - POSIX 解释器不支持 Windows 的 _pth 机制,stdlib 不 zip 化,条目保持
362
+ 散文件(与 .run 一致);
363
+ - app_name 写入 cookie,运行时缓存按应用分组并 LRU 清理旧版本。
364
+ """
365
+ host_platform = native_host_platform()
366
+ if host_platform != platform:
367
+ raise RuntimeError(
368
+ f"nexe 格式只能在本机对应平台上生成(当前: {host_platform or sys.platform},"
369
+ f"目标: {platform})。跨平台请用 run/tar.gz 格式。"
370
+ )
371
+ host_arch = native_host_arch()
372
+ if arch and arch != host_arch:
373
+ raise RuntimeError(
374
+ f"nexe 格式仅支持本机架构 {host_arch}(目标: {arch})。跨平台请用 run/tar.gz 格式。"
375
+ )
376
+ if logger:
377
+ logger.info("打包为原生单文件 (%s/%s, %s 子系统)",
378
+ host_platform, host_arch, "GUI" if not console else "console")
379
+ boot = ensure_bootloader_native(console, logger)
380
+ return _write_archive(boot.read_bytes(), bundle_dir, out, python,
381
+ zipify=False, app_name=app_name)
382
+
383
+
384
+ def parse_archive(path: Path) -> dict:
385
+ """解析自研归档(自校验用)。"""
386
+ data = path.read_bytes()
387
+ if len(data) < COOKIE_SIZE:
388
+ raise ValueError("文件过小")
389
+ cookie = data[-COOKIE_SIZE:]
390
+ if cookie[:8] != MAGIC:
391
+ raise ValueError("cookie 校验失败,不是 Pythub 自研归档")
392
+ payload_offset, toc_offset, toc_size = struct.unpack_from("<QQQ", cookie, 8)
393
+ md5 = cookie[32:64].rstrip(b"\0").decode("ascii")
394
+ app = cookie[64:96].rstrip(b"\0").decode("ascii")
395
+ body = data[payload_offset:toc_offset + toc_size]
396
+ if hashlib.md5(body).hexdigest() != md5:
397
+ raise ValueError("归档内容 MD5 校验失败")
398
+ count = struct.unpack_from("<I", data, toc_offset)[0]
399
+ pos = toc_offset + 4
400
+ entries: List[Tuple[str, int, int, int, int]] = []
401
+ for _ in range(count):
402
+ plen, stored, raw, off, flags = struct.unpack_from(_TOC_ITEM_FMT, data, pos)
403
+ pos += struct.calcsize(_TOC_ITEM_FMT)
404
+ name = data[pos:pos + plen].decode("utf-8")
405
+ pos += plen
406
+ _check_path(name)
407
+ entries.append((name, off, stored, raw, flags))
408
+ return {
409
+ "bootloader_size": payload_offset,
410
+ "entry_count": count,
411
+ "md5": md5,
412
+ "app": app,
413
+ "entries": entries,
414
+ }
pythub/formats.py ADDED
@@ -0,0 +1,227 @@
1
+ """目标平台产物格式实现:启动器、.app、dmg、pkg、AppImage、单文件 .run、单文件 .exe。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import io
7
+ import logging
8
+ import shutil
9
+ import subprocess
10
+ import tarfile
11
+ from pathlib import Path
12
+ from typing import Optional
13
+
14
+ from pythub.exe_archive import ( # noqa: F401 自研单文件打包器
15
+ make_exe,
16
+ make_native_exe,
17
+ native_host_arch,
18
+ native_host_platform,
19
+ )
20
+
21
+ from pythub.utils import find_executable, make_tar_gz, set_executable, zip_dir
22
+
23
+
24
+ def unix_launcher(main_name: str, python_rel: str, pyz_rel: str) -> str:
25
+ return (
26
+ "#!/bin/sh\n"
27
+ 'DIR="$(cd "$(dirname "$0")" && pwd)"\n'
28
+ f'exec "$DIR/{python_rel}" "$DIR/{pyz_rel}" "$@"\n'
29
+ )
30
+
31
+
32
+ def app_launcher(main_name: str) -> str:
33
+ return (
34
+ "#!/bin/sh\n"
35
+ 'DIR="$(cd "$(dirname "$0")" && pwd)"\n'
36
+ 'RES="$DIR/../Resources"\n'
37
+ 'exec "$RES/runtime/bin/python3" "$RES/app.pyz" "$@"\n'
38
+ )
39
+
40
+
41
+ def windows_launcher(main_name: str) -> str:
42
+ return (
43
+ "@echo off\r\n"
44
+ f'"%~dp0runtime\\python.exe" "%~dp0app.pyz" %*\r\n'
45
+ )
46
+
47
+
48
+ def apprun_launcher() -> str:
49
+ return (
50
+ "#!/bin/sh\n"
51
+ 'DIR="$(dirname "$(readlink -f "$0")")"\n'
52
+ 'exec "$DIR/runtime/bin/python3" "$DIR/app.pyz" "$@"\n'
53
+ )
54
+
55
+
56
+ INFO_PLIST_TEMPLATE = """<?xml version="1.0" encoding="UTF-8"?>
57
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
58
+ <plist version="1.0">
59
+ <dict>
60
+ <key>CFBundleName</key><string>{name}</string>
61
+ <key>CFBundleDisplayName</key><string>{name}</string>
62
+ <key>CFBundleIdentifier</key><string>org.crogram.{name}</string>
63
+ <key>CFBundleExecutable</key><string>{name}</string>
64
+ <key>CFBundlePackageType</key><string>APPL</string>
65
+ <key>CFBundleShortVersionString</key><string>{version}</string>
66
+ <key>CFBundleVersion</key><string>{version}</string>
67
+ <key>CFBundleInfoDictionaryVersion</key><string>6.0</string>
68
+ <key>LSMinimumSystemVersion</key><string>10.13</string>
69
+ <key>NSHighResolutionCapable</key><true/>
70
+ <key>LSApplicationCategoryType</key><string>public.app-category.developer-tools</string>
71
+ </dict>
72
+ </plist>
73
+ """
74
+
75
+
76
+ def build_app_bundle(
77
+ dest: Path,
78
+ name: str,
79
+ version: str,
80
+ runtime_src: Path,
81
+ pyz_src: Path,
82
+ logger: Optional[logging.Logger] = None,
83
+ ) -> Path:
84
+ """组装 macOS .app Bundle。"""
85
+ app = dest / f"{name}.app"
86
+ if app.exists():
87
+ shutil.rmtree(app)
88
+ contents = app / "Contents"
89
+ macos_dir = contents / "MacOS"
90
+ res_dir = contents / "Resources"
91
+ macos_dir.mkdir(parents=True)
92
+ res_dir.mkdir(parents=True)
93
+
94
+ (contents / "Info.plist").write_text(
95
+ INFO_PLIST_TEMPLATE.format(name=name, version=version), encoding="utf-8"
96
+ )
97
+ (contents / "PkgInfo").write_text("APPL????", encoding="utf-8")
98
+ shutil.copy2(pyz_src, res_dir / "app.pyz")
99
+ # 保留符号链接(bin/python3 -> python3.12 等),避免目标文件被重复复制
100
+ shutil.copytree(runtime_src, res_dir / "runtime", symlinks=True)
101
+ launcher = macos_dir / name
102
+ launcher.write_text(app_launcher(name), encoding="utf-8", newline="\n")
103
+ set_executable(launcher)
104
+ return app
105
+
106
+
107
+ def make_dmg(src_dir: Path, out: Path, name: str) -> Path:
108
+ """hdiutil 打包 DMG(仅 macOS 可用)。"""
109
+ out.parent.mkdir(parents=True, exist_ok=True)
110
+ subprocess.run(
111
+ ["hdiutil", "create", "-volname", name, "-srcfolder", str(src_dir),
112
+ "-ov", "-format", "UDZO", str(out)],
113
+ check=True, capture_output=True,
114
+ )
115
+ return out
116
+
117
+
118
+ def make_pkg(src_dir: Path, out: Path, name: str, version: str) -> Path:
119
+ """pkgbuild 打包 PKG(仅 macOS 可用),安装位置为 /Applications。
120
+
121
+ pkgbuild 默认 --install-location 是 /,应用会被装到文件系统根目录导致"找不到应用",
122
+ 因此显式指定安装到 /Applications。
123
+ """
124
+ out.parent.mkdir(parents=True, exist_ok=True)
125
+ subprocess.run(
126
+ ["pkgbuild", "--root", str(src_dir), "--identifier", f"org.crogram.{name}",
127
+ "--version", version, "--install-location", "/Applications", str(out)],
128
+ check=True, capture_output=True,
129
+ )
130
+ return out
131
+
132
+
133
+ def make_appimage(
134
+ staging: Path,
135
+ out: Path,
136
+ name: str,
137
+ runtime_src: Path,
138
+ pyz_src: Path,
139
+ logger: Optional[logging.Logger] = None,
140
+ ) -> Optional[Path]:
141
+ """组装 AppDir 并调用 appimagetool 生成 AppImage。"""
142
+ tool = find_executable("appimagetool")
143
+ if not tool:
144
+ return None
145
+ appdir = staging / "AppDir"
146
+ appdir.mkdir(parents=True, exist_ok=True)
147
+ shutil.copy2(pyz_src, appdir / "app.pyz")
148
+ shutil.copytree(runtime_src, appdir / "runtime", symlinks=True)
149
+ launcher = appdir / "AppRun"
150
+ launcher.write_text(apprun_launcher(), encoding="utf-8", newline="\n")
151
+ set_executable(launcher)
152
+ desktop = appdir / f"{name}.desktop"
153
+ desktop.write_text(
154
+ f"[Desktop Entry]\nType=Application\nName={name}\n"
155
+ f"Exec=AppRun\nIcon={name}\nCategories=Development;\n",
156
+ encoding="utf-8",
157
+ )
158
+ out.parent.mkdir(parents=True, exist_ok=True)
159
+ subprocess.run([tool, str(appdir), str(out)], check=True)
160
+ return out
161
+
162
+
163
+ def make_exe_zip(bundle_dir: Path, out: Path) -> Path:
164
+ """把自包含目录压缩为 .exe.zip(目录内含启动器,解压即用)。"""
165
+ out.parent.mkdir(parents=True, exist_ok=True)
166
+ zip_dir(out, bundle_dir)
167
+ return out
168
+
169
+
170
+ # ---------------------------------------------------------------- 单文件 .run
171
+
172
+ RUN_HEADER_TEMPLATE = """#!/bin/sh
173
+ # Pythub 自解压单文件可执行(makeself 风格)
174
+ # 任意主机平台可交叉生成(引导头为纯文本脚本,无需任何工具链);
175
+ # 目标机无需安装 Python,首次运行解压内嵌运行时到缓存目录,之后直接启动。
176
+ APP_NAME="{app}"
177
+ SKIP_BYTES="0000000000"
178
+ CACHE="$HOME/.cache/pythub/run/$APP_NAME/{md5}"
179
+ if [ ! -f "$CACHE/.pythub-run-ok" ]; then
180
+ echo "首次运行,正在解压到 $CACHE ..."
181
+ rm -rf "$CACHE"
182
+ mkdir -p "$CACHE"
183
+ # 用 $(( )) 算术展开取偏移: 空格补位既避免 BSD tail 的八进制陷阱,
184
+ # 又保持引导头字节数恒定;$(( )) 不做字段分割,+ 与数字不会分开
185
+ tail -c +$((SKIP_BYTES)) "$0" | tar xzf - -C "$CACHE" \\
186
+ || {{ echo "错误: 自解压失败,文件可能已损坏" >&2; exit 1; }}
187
+ [ -f "$CACHE/{app}" ] \\
188
+ || {{ echo "错误: 启动器未生成,解压可能失败" >&2; exit 1; }}
189
+ touch "$CACHE/.pythub-run-ok" 2>/dev/null
190
+ # 缓存清理: 同一应用旧 md5 缓存目录 LRU 清理(仅保留当前版本)
191
+ for _old in "$HOME/.cache/pythub/run/$APP_NAME"/*/; do
192
+ [ "$_old" = "$CACHE/" ] || rm -rf "$_old" 2>/dev/null
193
+ done
194
+ fi
195
+ exec "$CACHE/{app}" "$@"
196
+ """
197
+
198
+ # 占位串含引号,确保不会与 md5 十六进制串混淆;替换后长度不变,保证字节偏移计算正确
199
+ _SKIP_PLACEHOLDER = '"0000000000"'
200
+
201
+
202
+ def make_run(bundle_dir: Path, out: Path, name: str) -> Path:
203
+ """组装 Linux 单文件自解压可执行(.run)。
204
+
205
+ 结构: [ sh 引导头 ][ 追加的 tar.gz 数据 ]。引导头用 tail 按字节偏移
206
+ 切出自身尾部数据并解压到缓存目录,然后调起其中的启动器。
207
+ """
208
+ if any(c in name for c in '"\'`$\\'):
209
+ raise ValueError(f"应用名称包含不安全字符: {name!r}")
210
+
211
+ buf = io.BytesIO()
212
+ with tarfile.open(fileobj=buf, mode="w:gz") as tf:
213
+ tf.add(str(bundle_dir), arcname=".")
214
+ payload = buf.getvalue()
215
+
216
+ header = RUN_HEADER_TEMPLATE.format(app=name, md5=hashlib.md5(payload).hexdigest())
217
+ # 数据从引导头之后第一个字节开始;tail -c +N 为 1 起始偏移。
218
+ # 用空格右对齐补位: 未加引号的 $SKIP_BYTES 展开时 POSIX 字段分割会丢弃前导空格
219
+ skip = len(header.encode("utf-8")) + 1
220
+ header = header.replace(_SKIP_PLACEHOLDER, '"' + str(skip).rjust(10) + '"', 1)
221
+
222
+ out.parent.mkdir(parents=True, exist_ok=True)
223
+ with open(out, "wb") as f:
224
+ f.write(header.encode("utf-8"))
225
+ f.write(payload)
226
+ set_executable(out)
227
+ return out