@harmonyos-arkts/d2h 0.1.20 → 0.1.21

package/skills/cpp/d2h-native-library-build/scripts/check-android-so.py

@@ -0,0 +1,580 @@
+#!/usr/bin/env python3
+"""迁移前检查：Android 工程中已有的 .so / .a 能否直接用于 HarmonyOS。
+
+跨平台（macOS / Linux / Windows）：
+- 不依赖 `file`，文件类型用魔数判断（ELF / ar archive），架构用 llvm-readelf/readelf。
+- 依赖工具优先找 `llvm-readelf` / `llvm-nm` / `llvm-objdump`（Android NDK 与
+  DevEco/OpenHarmony SDK 均自带，且三平台同名同输出格式）；缺省时自动从常见
+  SDK 安装目录（ANDROID_NDK_HOME / ANDROID_HOME / OHOS_SDK_HOME / DevEco 内置 SDK）发现。
+
+用法
+----
+    python3 check-android-so.py [项目目录] [--json] [--no-build-dirs]
+    python3 check-android-so.py <项目目录> --from-facts <facts/native-libs.json> [--json]
+
+`--from-facts` 按 AppGraph `facts/native-libs.json` 分片的产物清单只深度检查
+其中列出的 .so/.a（路径相对工程目录），避免与分片扫描器各自重扫导致清单分叉；
+分片的 ①②③ 初分类（usageCase/facts_usage）会一并写入报告供对账。
+
+退出码
+------
+    0  正常完成（含“存在不可直接用”的库）
+    2  缺少必要的工具（llvm-readelf/readelf 与 llvm-nm/nm）或分片不可读
+"""
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+ANDROID_ONLY_NEEDED = {
+    "liblog.so",
+    "libandroid.so",
+    "libnativehelper.so",
+    "libjnigraphics.so",
+    "libcamera2ndk.so",
+    "libmediandk.so",
+    "libOpenSLES.so",
+    "libaaudio.so",
+    "libamidi.so",
+    "libbinder_ndk.so",
+    "libneuralnetworks.so",
+    "libEGL.so",
+    "libGLESv1_CM.so",
+    "libGLESv2.so",
+    "libGLESv3.so",
+    "libandroid_runtime.so",
+}
+
+ANDROID_SYMBOL_PREFIXES = (
+    "__android_log",
+    "AAssetManager",
+    "ANativeWindow",
+    "ANativeActivity",
+    "AInputQueue",
+    "AChoreographer",
+    "AHardwareBuffer",
+    "ACamera",
+    "AMedia",
+    "ASensor",
+    "AImage",
+    "android_",
+)
+
+EXCLUDE_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", "oh_modules", ".hvigor",
+    ".gradle", "build", ".idea", ".cxx", ".externalNativeBuild",
+}
+
+NATIVE_BUILD_FILES = {"CMakeLists.txt", "Android.mk", "Application.mk", "Makefile", "configure.ac"}
+NATIVE_SOURCE_EXTS = {".c", ".cpp", ".cc", ".cxx", ".h", ".hpp"}
+PATCH_EXTS = {".patch", ".diff"}
+
+TOOL_NAMES = {
+    "readelf": ["llvm-readelf", "readelf", "greadelf", "readelf.exe", "llvm-readelf.exe"],
+    "objdump": ["llvm-objdump", "objdump", "gobjdump", "objdump.exe", "llvm-objdump.exe"],
+    "nm": ["llvm-nm", "nm", "gnm", "nm.exe", "llvm-nm.exe"],
+}
+
+
+def run(cmd):
+    try:
+        return subprocess.run(
+            cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+            text=True, errors="replace",
+        ).stdout
+    except OSError:
+        return ""
+
+
+def is_windows():
+    return os.name == "nt"
+
+
+def expand_env(*names):
+    for n in names:
+        v = os.environ.get(n)
+        if v:
+            yield v
+
+
+def sdk_bin_dirs():
+    dirs = []
+
+    def add_ndk_bin(ndk_root):
+        if not ndk_root or not os.path.isdir(ndk_root):
+            return
+        prebuilt = os.path.join(ndk_root, "toolchains", "llvm", "prebuilt")
+        if os.path.isdir(prebuilt):
+            for host in os.listdir(prebuilt):
+                bin_dir = os.path.join(prebuilt, host, "bin")
+                if os.path.isdir(bin_dir):
+                    dirs.append(bin_dir)
+
+    for ndk in expand_env("ANDROID_NDK_HOME", "ANDROID_NDK_ROOT", "NDK_HOME"):
+        add_ndk_bin(ndk)
+
+    for sdk in expand_env("ANDROID_HOME", "ANDROID_SDK_ROOT"):
+        ndk_root = os.path.join(sdk, "ndk")
+        if os.path.isdir(ndk_root):
+            for ndk in os.listdir(ndk_root):
+                add_ndk_bin(os.path.join(ndk_root, ndk))
+
+    for sdk in expand_env("OHOS_SDK_HOME", "DEVECO_SDK_HOME", "OHOS_NDK_HOME", "OHOS_NATIVE_HOME"):
+        for sub in ("llvm/bin", os.path.join("native", "llvm", "bin")):
+            d = os.path.join(sdk, sub)
+            if os.path.isdir(d):
+                dirs.append(d)
+
+    home = os.path.expanduser("~")
+    for base in (
+        os.path.join(home, "Library", "OpenHarmony", "Sdk"),            # macOS
+        os.path.join(home, "AppData", "Local", "OpenHarmony", "Sdk"),   # Windows
+        os.path.join(home, ".local", "share", "OpenHarmony", "Sdk"),    # Linux
+        os.path.join(home, "Huawei", "Sdk"),
+    ):
+        if os.path.isdir(base):
+            for sub in ("native/llvm/bin", "llvm/bin"):
+                d = os.path.join(base, sub)
+                if os.path.isdir(d):
+                    dirs.append(d)
+    return dirs
+
+
+def resolve_tools():
+    tools = {}
+    bin_dirs = sdk_bin_dirs()
+    for role, names in TOOL_NAMES.items():
+        path = None
+        for n in names:
+            p = shutil.which(n)
+            if p:
+                path = p
+                break
+        if not path:
+            for d in bin_dirs:
+                for n in names:
+                    candidate = os.path.join(d, n)
+                    if os.path.isfile(candidate):
+                        path = candidate
+                        break
+                if path:
+                    break
+        tools[role] = path
+    return tools
+
+
+def file_kind(path):
+    with open(path, "rb") as f:
+        head = f.read(8)
+    if head.startswith(b"\x7fELF"):
+        return "elf"
+    if head.startswith(b"!<arch>\n"):
+        return "ar"
+    return "unknown"
+
+
+def map_machine(machine):
+    machine = machine.strip()
+    if machine == "AArch64":
+        return "arm64-v8a", 64
+    if machine == "ARM":
+        return "armeabi-v7a", 32
+    if machine in ("X86-64", "Advanced Micro Devices X86-64", "AMD x86-64"):
+        return "x86_64", 64
+    if machine in ("Intel 80386", "i386", "80386"):
+        return "x86", 32
+    if "LoongArch" in machine:
+        return "loongarch64", 64
+    if "RISC-V" in machine:
+        return "riscv64", 64
+    return "unknown", None
+
+
+def read_arch_readelf(out):
+    bits = None
+    m = re.search(r"Class:\s*(ELF64|ELF32)", out)
+    if m:
+        bits = 64 if m.group(1) == "ELF64" else 32
+    machine = ""
+    m = re.search(r"Machine:\s*(.+)", out)
+    if m:
+        machine = m.group(1)
+    arch, arch_bits = map_machine(machine)
+    if arch != "unknown":
+        return arch, bits if bits is not None else arch_bits
+    return arch, bits
+
+
+def read_arch_objdump(out):
+    m = re.search(r"architecture:\s*([^\s,]+)", out)
+    if m:
+        arch, bits = map_machine(m.group(1))
+        if arch != "unknown":
+            return arch, bits
+    return "unknown", None
+
+
+def inspect_elf(path, tools):
+    info = {
+        "path": path,
+        "kind": "so",
+        "arch": "unknown",
+        "bits": None,
+        "soname": None,
+        "needed": [],
+        "android_needed": [],
+        "jni": False,
+        "jni_symbols": [],
+        "bionic_versioned": False,
+        "android_symbols": [],
+        "android_signals": [],
+        "direct_usable": None,
+        "reason": "",
+    }
+
+    arch_out = run([tools["readelf"], "-h", path]) if tools["readelf"] else ""
+    if arch_out and "ELF Header" in arch_out:
+        info["arch"], info["bits"] = read_arch_readelf(arch_out)
+    elif tools["objdump"]:
+        info["arch"], info["bits"] = read_arch_objdump(run([tools["objdump"], "-f", path]))
+
+    dyn_out = run([tools["readelf"], "-d", path]) if tools["readelf"] else ""
+    needed = re.findall(r"\(NEEDED\)\s+Shared library:\s*\[([^\]]+)\]", dyn_out)
+    if not needed and tools["objdump"]:
+        objdump_out = run([tools["objdump"], "-p", path])
+        needed = re.findall(r"^\s*NEEDED\s+(\S+)", objdump_out, re.MULTILINE)
+    for lib in needed:
+        info["needed"].append(lib)
+        if lib in ANDROID_ONLY_NEEDED:
+            info["android_needed"].append(lib)
+
+    m = re.search(r"\(SONAME\)\s+Library soname:\s*\[([^\]]+)\]", dyn_out)
+    if m:
+        info["soname"] = m.group(1)
+    elif tools["objdump"]:
+        objdump_out = run([tools["objdump"], "-p", path])
+        m = re.search(r"^\s*SONAME\s+(\S+)", objdump_out, re.MULTILINE)
+        if m:
+            info["soname"] = m.group(1)
+
+    if tools["nm"]:
+        defined = run([tools["nm"], "-D", "--defined-only", "--extern-only", "-j", path])
+        for sym in defined.splitlines():
+            sym = sym.strip()
+            if sym.startswith("Java_") or sym in ("JNI_OnLoad", "JNI_OnUnload"):
+                info["jni"] = True
+                info["jni_symbols"].append(sym)
+
+        undefined = run([tools["nm"], "-D", "-u", "-P", path])
+        for line in undefined.splitlines():
+            parts = line.split()
+            sym = parts[0] if parts else ""
+            if "@" in sym:
+                info["bionic_versioned"] = True
+            if any(sym.startswith(p) for p in ANDROID_SYMBOL_PREFIXES):
+                info["android_symbols"].append(sym)
+
+    if info["jni"]:
+        info["android_signals"].append("JNI 桥接（Java_* / JNI_OnLoad）")
+    if info["android_needed"]:
+        info["android_signals"].append("依赖 Android 系统库：" + ", ".join(info["android_needed"]))
+    if info["bionic_versioned"]:
+        info["android_signals"].append("符号带 Bionic 版本（@LIBC/@LIBLOG…）")
+    if info["android_symbols"]:
+        info["android_signals"].append("引用 Android NDK 专用符号：" + ", ".join(sorted(set(info["android_symbols"]))[:5]))
+
+    is_android = bool(info["android_signals"])
+    if is_android:
+        info["direct_usable"] = False
+        info["reason"] = "；".join(info["android_signals"])
+    else:
+        info["direct_usable"] = True
+        info["reason"] = "未检测到 Android 特征（无 JNI、无 Android 系统库依赖、符号无 Bionic 版本），可能已是鸿蒙/musl 编译产物"
+    return info
+
+
+def inspect_archive(path, tools):
+    info = {
+        "path": path,
+        "kind": "a",
+        "arch": "unknown",
+        "bits": None,
+        "soname": None,
+        "needed": [],
+        "android_needed": [],
+        "jni": False,
+        "jni_symbols": [],
+        "bionic_versioned": False,
+        "android_symbols": [],
+        "android_signals": ["静态库(.a)"],
+        "direct_usable": False,
+        "reason": "静态库(.a)：对象文件以 aarch64-linux-android 三元组编译，链接进鸿蒙会失败，必须用 OHOS 工具链重编",
+    }
+    if tools["nm"]:
+        syms = run([tools["nm"], "-P", path])
+        for line in syms.splitlines():
+            parts = line.split()
+            sym = parts[0] if parts else ""
+            if "@" in sym:
+                info["bionic_versioned"] = True
+            if any(sym.startswith(p) for p in ANDROID_SYMBOL_PREFIXES):
+                info["android_symbols"].append(sym)
+        if info["bionic_versioned"]:
+            info["android_signals"].append("对象符号带 Bionic 版本")
+        if info["android_symbols"]:
+            info["android_signals"].append("引用 Android NDK 专用符号：" + ", ".join(sorted(set(info["android_symbols"]))[:5]))
+        info["reason"] = "；".join(info["android_signals"])
+    return info
+
+
+def classify_case(info, evidence):
+    if not info["direct_usable"]:
+        if evidence["has_patch"] and evidence["has_source"]:
+            return 2
+        if evidence["has_source"]:
+            return 1
+        return 3
+    return None
+
+
+def build_solution(info, case):
+    if info["direct_usable"]:
+        return ["可直接放入鸿蒙工程 libs/<abi>/ 并通过 NAPI 或 ArkTS import 使用；仍建议核对 ABI（arm64-v8a）是否齐全。"]
+
+    if case == 1:
+        return [
+            "1) 保留源码，将构建脚本改写为鸿蒙 CMake（目标三元组 aarch64-linux-ohos，日志库换 libhilog_ndk.z.so）。",
+            "2) JNI 桥接层改写为 NAPI（参考 references/jni-to-napi-mapping.md）。",
+            "3) 在 build-profile.json5 配 externalNativeOptions + abiFilters 编进 HAP。",
+        ]
+    if case == 2:
+        return [
+            "1) 在 OHOS 工具链下重放修改脚本/patch；逐条适配 patch 中的 Android 特有代码（__ANDROID__ 宏、__android_log_print、AAssetManager 等）。",
+            "2) JNI 桥接层改写为 NAPI。",
+            "3) 重新交叉编译（--target=aarch64-linux-ohos）并编进 HAP。",
+        ]
+    return [
+        "1) 无源码，预编译 .so 无法在鸿蒙直接加载，需先查鸿蒙替代：用 native-library-substitution（ohpm 2678 映射）或厂商官方鸿蒙 SDK。",
+        "2) 若上游开源，则退回情况一/二，获取源码后用 OHOS 工具链重编。",
+        "3) 无源码且无替代：用鸿蒙系统 API 重实现或功能裁剪，并在风险清单标记 high。",
+    ]
+
+
+def scan_evidence(root):
+    evidence = {"has_source": False, "has_patch": False, "has_build_files": False, "native_dirs": []}
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS]
+        base = os.path.basename(dirpath)
+        if base in ("jni", "cpp", "native") or "native" in base:
+            evidence["native_dirs"].append(dirpath)
+        for fn in filenames:
+            if fn in NATIVE_BUILD_FILES:
+                evidence["has_build_files"] = True
+            ext = os.path.splitext(fn)[1].lower()
+            if ext in NATIVE_SOURCE_EXTS:
+                evidence["has_source"] = True
+            if ext in PATCH_EXTS:
+                evidence["has_patch"] = True
+            if fn.endswith((".sh", ".mk")) and fn not in ("Android.mk", "Application.mk"):
+                evidence["has_patch"] = True
+    return evidence
+
+
+def find_native_libs(root):
+    results = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS]
+        for fn in filenames:
+            if fn.endswith(".so") or fn.endswith(".a"):
+                results.append(os.path.join(dirpath, fn))
+    return sorted(results)
+
+
+def load_facts(path):
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            shard = json.load(f)
+    except (OSError, ValueError) as e:
+        print("无法读取 facts 分片: %s (%s)" % (path, e))
+        return None
+    if shard.get("kind") != "native-lib-facts" or not isinstance(shard.get("nativeLibs"), dict):
+        print("分片不是合法的 native-lib-facts: %s" % path)
+        return None
+    return shard["nativeLibs"]
+
+
+def libs_from_facts(root, native_libs):
+    """把分片 libraries[].artifacts[].path 解析为绝对路径清单，返回 (排序路径, 路径→usage 映射)。"""
+    usage_by_path = {}
+    for lib in native_libs.get("libraries", []):
+        for artifact in lib.get("artifacts", []):
+            rel = artifact.get("path")
+            if not rel:
+                continue
+            absolute = os.path.normpath(os.path.join(root, *rel.split("/")))
+            usage_by_path[absolute] = lib.get("usage")
+    return sorted(usage_by_path.keys()), usage_by_path
+
+
+def main():
+    parser = argparse.ArgumentParser(description="检查 Android .so/.a 能否直接用于鸿蒙")
+    parser.add_argument("target", nargs="?", default=".", help="Android 工程目录（默认当前目录）")
+    parser.add_argument("--json", action="store_true", help="输出 JSON")
+    parser.add_argument("--no-build-dirs", action="store_true", help="跳过 build 目录扫描")
+    parser.add_argument("--from-facts", metavar="PATH", help="按 facts/native-libs.json 分片清单只检查列出的产物（路径相对工程目录）")
+    args = parser.parse_args()
+
+    tools = resolve_tools()
+    if not tools["readelf"] and not tools["objdump"]:
+        print("缺少 ELF 解析工具（llvm-readelf / readelf / objdump）。")
+        print("Android NDK 与 DevEco/OpenHarmony SDK 均自带 llvm-readelf/llvm-nm/llvm-objdump，")
+        print("请将其加入 PATH，或设置 ANDROID_NDK_HOME / OHOS_SDK_HOME 后重试。")
+        return 2
+    if not tools["nm"]:
+        print("缺少符号解析工具（llvm-nm / nm），将跳过 JNI/Bionic 符号检测，仅做依赖检查。")
+
+    root = os.path.abspath(args.target)
+    if args.no_build_dirs:
+        EXCLUDE_DIRS.add("build")
+
+    native_libs = None
+    if args.from_facts:
+        native_libs = load_facts(os.path.abspath(args.from_facts))
+        if native_libs is None:
+            return 2
+
+    if native_libs is not None:
+        libs, usage_by_path = libs_from_facts(root, native_libs)
+    else:
+        libs, usage_by_path = find_native_libs(root), {}
+    evidence = scan_evidence(root)
+
+    report = []
+    for path in libs:
+        if not os.path.isfile(path):
+            info = {
+                "path": path, "kind": "unknown", "arch": "unknown", "bits": None,
+                "soname": None, "needed": [], "android_needed": [], "jni": False,
+                "jni_symbols": [], "bionic_versioned": False, "android_symbols": [],
+                "android_signals": [], "direct_usable": False,
+                "reason": "分片列出但工程中不存在该文件",
+            }
+        else:
+            kind = file_kind(path)
+            if kind == "ar":
+                info = inspect_archive(path, tools)
+            elif kind == "elf":
+                info = inspect_elf(path, tools)
+            else:
+                info = {
+                    "path": path, "kind": "unknown", "arch": "unknown", "bits": None,
+                    "soname": None, "needed": [], "android_needed": [], "jni": False,
+                    "jni_symbols": [], "bionic_versioned": False, "android_symbols": [],
+                    "android_signals": [], "direct_usable": False,
+                    "reason": "无法识别的文件类型（非 ELF 非 ar archive）",
+                }
+        case = classify_case(info, evidence)
+        info["usage_case"] = case
+        info["solution"] = build_solution(info, case)
+        if path in usage_by_path:
+            info["facts_usage"] = usage_by_path[path]
+        report.append(info)
+
+    jni_reconciliation = None
+    if native_libs is not None:
+        exported = set()
+        for info in report:
+            for sym in info.get("jni_symbols", []):
+                if sym.startswith("Java_"):
+                    exported.add(sym)
+        declared = native_libs.get("jniMethods", [])
+        declared_names = [m.get("name") for m in declared if m.get("name")]
+        unmatched_declared = [
+            m for m in declared
+            if m.get("name") and not any(s.endswith("_" + m["name"]) for s in exported)
+        ]
+        unmatched_exports = [
+            s for s in sorted(exported)
+            if not any(s.endswith("_" + n) for n in declared_names)
+        ]
+        jni_reconciliation = {
+            "declared": len(declared),
+            "exported": len(exported),
+            "unmatched_declared": unmatched_declared,
+            "unmatched_exports": unmatched_exports,
+            "note": "按 JNI 符号方法名后缀对账（Java_<类>_<方法>）。Kotlin 文件级 external fun 编译为 <文件>Kt 类，重载/名称混淆/动态注册需人工复核；无 nm 工具时 exported 为空。",
+        }
+
+    if args.json:
+        payload = {"target": root, "evidence": evidence, "libraries": report}
+        if native_libs is not None:
+            payload["from_facts"] = os.path.abspath(args.from_facts)
+            payload["facts_usage_case"] = native_libs.get("usageCase")
+            payload["load_calls"] = native_libs.get("loadCalls", [])
+            payload["jni_reconciliation"] = jni_reconciliation
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return 0
+
+    print("=" * 72)
+    print("Android C/C++ 库迁移前检查报告")
+    print("工程目录:", root)
+    if native_libs is not None:
+        print("检查范围: facts/native-libs.json 分片清单（%d 个产物，初分类 %s）" % (len(libs), native_libs.get("usageCase")))
+    print("发现库文件:", len(libs), "个")
+    print("源码证据:", "有源码" if evidence["has_source"] else "无源码",
+          "| 构建脚本:", "有" if evidence["has_build_files"] else "无",
+          "| patch/修改脚本:", "有" if evidence["has_patch"] else "无")
+    print("=" * 72)
+
+    if not libs:
+        print("未发现 .so / .a 文件。")
+        return 0
+
+    for info in report:
+        print()
+        print("文件:", info["path"])
+        kind_label = {"so": "动态库(.so)", "a": "静态库(.a)", "unknown": "未知"}.get(info["kind"], info["kind"])
+        print("  类型:", kind_label, "| 架构:", info["arch"], "|", str(info["bits"]) + "位" if info["bits"] else "")
+        if info["soname"]:
+            print("  SONAME:", info["soname"])
+        if info["needed"]:
+            print("  动态依赖:", ", ".join(info["needed"]))
+        verdict = "可直接使用" if info["direct_usable"] else "不能直接使用"
+        print("  结论:", verdict)
+        print("  原因:", info["reason"] or "-")
+        if info["usage_case"]:
+            print("  使用方式分类: 情况%d" % info["usage_case"])
+        if info.get("facts_usage"):
+            print("  分片初分类:", info["facts_usage"])
+        for step in info["solution"]:
+            print("     ", step)
+
+    print()
+    if jni_reconciliation is not None:
+        print("JNI 桥接对账（分片 jniMethods ↔ .so 导出 Java_* 符号）:")
+        print("  声明 external/native 方法:", jni_reconciliation["declared"], "个")
+        print("  .so 导出 Java_* 符号:", jni_reconciliation["exported"], "个")
+        if jni_reconciliation["unmatched_declared"]:
+            print("  ⚠ 声明了方法但无对应导出符号（可能桥接缺失/动态注册/名称混淆）:")
+            for m in jni_reconciliation["unmatched_declared"]:
+                print("     - %s:%s %s(%s)" % (m.get("file"), m.get("line"), m.get("name"), m.get("language")))
+        if jni_reconciliation["unmatched_exports"]:
+            print("  ⚠ 导出了符号但未在源码声明（可能重载/额外 JNI 函数）:")
+            for s in jni_reconciliation["unmatched_exports"][:10]:
+                print("     -", s)
+        print()
+
+    print("=" * 72)
+    n_ok = sum(1 for r in report if r["direct_usable"])
+    n_bad = len(report) - n_ok
+    print("汇总: 可直接使用 %d 个，需处理 %d 个（全部需在鸿蒙侧重编或替代后才能使用）。" % (n_ok, n_bad))
+    print("=" * 72)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())