zarchive-py 0.0.1b3__tar.gz

zarchive_py-0.0.1b3/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include setup.py
+include _bundle_native.py
+include _plat.py
+include zarchive/_bin/.gitkeep
+recursive-exclude zarchive/_bin *.dll *.so *.dylib *.so.*
+graft tests
+global-exclude *.py[cod] __pycache__

zarchive_py-0.0.1b3/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: zarchive-py
+Version: 0.0.1b3
+Summary: Python bindings for the zArchive library (identify, create, read, extract, verify).
+Home-page: https://github.com/Leon-Zhang/lib_main
+Author: Leon Zhang
+Author-email: leonzh.work@outlook.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.8
+Description-Content-Type: text/plain
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-python
+Dynamic: summary
+
+zArchive reads and writes archive files (zip, gzip, bzip2, tar, 7z, cab, rar, and others): identify a file, open it, list and read members, extract, verify, and create new archives. This package calls that library from Python. The wheel includes the matching native library for the platform it was built on.

zarchive_py-0.0.1b3/README.md

@@ -0,0 +1,241 @@
+# zarchive-py
+
+Python ctypes bindings for the **zArchive** native library. Install from PyPI as `zarchive-py`; import the module as `zarchive`. The package wraps the C API in `zArchive/CApi.h` plus the older exports:
+
+- Identify archive paths (`zarchive_identify_*` / `ArchiveFSItemIdentifyA/W`)
+- Open, list, read, verify, and extract (`zarchive_open_w`, `zarchive_enum_items`, `zarchive_read_file_alloc_w`, `zarchive_extract_*`, `zarchive_verify_*`)
+- Create archives (`zarchive_create_begin_w`, `zarchive_add_*`, `zarchive_create_finish`, `zarchive_create_empty_w`)
+- `CreateCompressedFile` / `FreeCompressedFile` — allocate a format-specific `CArchive*` (zip, gz, bz, tar, 7z, cab, za, ...)
+- `zarchive_deinitialize` / `DeinitializeAll` — tear down native globals
+
+`pip install zarchive-py` installs a **platform wheel** that already embeds the native `zArchive` library under `zarchive/_bin`. pip selects the wheel that matches the install OS/arch. No manual copy of `zArchive.dll` / `libzArchive.so` / `libzArchive.dylib` is required after install.
+
+Published wheel tags:
+
+| Platform | Wheel tag | Native library |
+|---|---|---|
+| Windows x64 | `win_amd64` | `zArchive.dll` |
+| Linux x86_64 | `manylinux_2_28_x86_64` or `manylinux_2_35_x86_64` | `libzArchive.so` |
+| Linux aarch64 | `manylinux_*_aarch64` | `libzArchive.so` |
+| macOS Intel | `macosx_11_0_x86_64` | `libzArchive.dylib` |
+| macOS Apple Silicon | `macosx_11_0_arm64` | `libzArchive.dylib` |
+| iOS device | `ios_13_0_arm64_iphoneos` | `libzArchive.so` |
+| iOS simulator | `ios_13_0_arm64_iphonesimulator` or `ios_13_0_x86_64_iphonesimulator` | `libzArchive.so` |
+| Android | `android_21_arm64_v8a` (also `armeabi_v7a`, `x86_64`, `x86`) | `libzArchive.so` |
+
+The published `sdist` is source-only and cannot be installed without a native build.
+
+## Requirements
+
+- Python 3.8+ (`python` or `python3` on `PATH`)
+- A matching platform wheel. The published `sdist` is source-only.
+- To **build** a wheel: a native `zArchive` shared library for that OS/arch (see below). The build copies it into the package.
+
+DLL / shared-library search order at runtime:
+
+1. Extra paths passed to `resolve_dll_path`
+2. The installed package's `zarchive/_bin` directory
+3. Under `$WORKSPACE_PATH` and `$WORKSPACE_PATH/lib_main` (`bin/x64`, `bin/linux_x86_64`, `bin/macos_arm64`, `bin/ios_arm64_iphoneos`, `bin/android_arm64_v8a`, …)
+4. The same folders under the repo root
+
+## Build the native library
+
+Required only when creating a new wheel, not when installing from PyPI.
+
+**Windows:** from this directory, `build_native.bat` (or `powershell -File build_native.ps1`) builds `zArchive.vcxproj` as **Dynamic_Release|x64**. Output: `%WORKSPACE_PATH%\bin\x64\zArchive.dll`. Set `ZARCHIVE_VS_CONFIG=Dynamic_Debug` for `zArchived.dll`. Debug wheels also need sibling engine DLLs in `bin\x64` and the CUDA 12 runtime (`cudart64_12.dll`). Import libraries under `%WORKSPACE_PATH%\lib\x64` must already exist; this script builds the zArchive project, not the rest of the solution.
+
+**Linux / macOS:** on that OS, from this directory:
+
+```sh
+chmod +x build_native.sh
+./build_native.sh
+```
+
+`build_native.sh` does not run on Windows. It runs the CMake project at `build/cmake/zArchive` for the machine it is on (no cross-compile) and installs:
+
+- Linux x86_64: `bin/linux_x86_64/libzArchive.so` (and `bin/linux/`)
+- Linux aarch64: `bin/linux_aarch64/libzArchive.so`
+- macOS Intel: `bin/macos_x86_64/libzArchive.dylib` (and `bin/macos/`)
+- macOS Apple Silicon: `bin/macos_arm64/libzArchive.dylib`
+
+**iOS** (macOS with Xcode) and **Android** (NDK) are cross builds. They produce `libzArchive.so` and do not replace the host library.
+
+```sh
+chmod +x build_native_ios.sh build_native_android.sh
+./build_native_ios.sh
+./build_native_android.sh
+```
+
+- iOS device: `bin/ios_arm64_iphoneos/libzArchive.so` (`ZARCHIVE_IOS_SDK=iphoneos`, deployment target 13.0)
+- iOS simulator: `bin/ios_arm64_iphonesimulator/libzArchive.so` (`ZARCHIVE_IOS_SDK=iphonesimulator`)
+- Android arm64: `bin/android_arm64_v8a/libzArchive.so` (`ZARCHIVE_ANDROID_ABI=arm64-v8a`, API 21)
+
+On Windows the Android NDK build is `build_native_android.bat`. Install and smoke tests for those wheels run only under CPython with `sys.platform` of `ios` or `android`:
+
+```sh
+./devops/ios/_ios_install_test.sh
+./devops/android/_android_install_test.sh
+```
+
+CMake needs a C++14 compiler. The shared library compiles zArchive plus sibling engine sources (`ZARCHIVE_EMBED_DEPS=ON`). Build each desktop architecture on a machine of that architecture. iOS and Android use the cross scripts above.
+
+Ubuntu packages the script can pick up: `python3-dev`, `libmysqlclient-dev`, `liblua5.3-dev`, `mono-devel`, and `libnode-dev`. On macOS the same script looks up Homebrew (`python@3`, `mysql-client`, `lua`, `mono`, `node`) and the active `python3` include path, and sets `MACOSX_DEPLOYMENT_TARGET` to `11.0` when it is unset so the dylib matches the `macosx_11_0_*` wheel tag. Ogg/Vorbis headers ship in `extlib`.
+
+GitHub Actions workflow `.github/workflows/zarchive-wheels.yml` builds the Linux and macOS wheels on `ubuntu-22.04`, `macos-13`, and `macos-14`.
+
+## Build the Python package
+
+From this directory (`build/Python/zArchive`).
+
+Windows:
+
+```bat
+build_package.bat
+```
+
+Linux / macOS:
+
+```sh
+chmod +x build_package.sh
+./build_package.sh
+```
+
+That stages the native library into `zarchive/_bin`, then writes:
+
+- `dist/zarchive_py-0.0.1-py3-none-<platform>.whl` (embeds native libs)
+- `dist/zarchive_py-0.0.1.tar.gz` (source only)
+
+Equivalent: `build_package.ps1` or `python build_wheels.py`. A `py3-none-any` wheel is not produced.
+
+To package extra wheels from natives already sitting under `bin/linux_*` or `bin/macos_*` (even on another OS):
+
+```sh
+python build_wheels.py --all
+# or one target
+python build_wheels.py --plat manylinux_2_28_x86_64 --native-dir ../../../../bin/linux_x86_64
+```
+
+Override the wheel tag with `ZARCHIVE_WHEEL_PLAT` and the library folder with `ZARCHIVE_NATIVE_DIR`. On Linux, `ZARCHIVE_MANYLINUX` defaults to `manylinux_2_28`.
+
+Install the wheel into the current interpreter:
+
+```bat
+python -m pip install --force-reinstall dist\zarchive_py-0.0.1-py3-none-win_amd64.whl
+```
+
+```sh
+python3 -m pip install --force-reinstall dist/zarchive_py-0.0.1-py3-none-*.whl
+```
+
+After uploading every platform wheel to the same PyPI version, `pip install zarchive-py` picks the file for the current OS.
+
+## Publish to PyPI
+
+Scripts live in `build/Python` (default package folder is `zArchive`). Set `TWINE_USERNAME=__token__` and `TWINE_PASSWORD` to a PyPI/TestPyPI API token, or write `%USERPROFILE%\.pypirc`.
+
+```bat
+cd /d ..
+publish_check.bat
+publish_testpypi.bat
+publish_pypi.bat
+```
+
+```sh
+cd ..
+./publish_check.sh
+./publish_testpypi.sh
+./publish_pypi.sh
+```
+
+Production upload prompts for `YES` unless `PYPI_UPLOAD_CONFIRM=YES`. The PyPI project name is `zarchive-py`. After upload:
+
+```bat
+python -m pip install zarchive-py
+```
+
+## Run tests
+
+Uses the bundled native library in `zarchive/_bin` after a package build, or a workspace build via `WORKSPACE_PATH`.
+
+```bat
+test_package.bat
+```
+
+```sh
+chmod +x test_package.sh
+./test_package.sh
+```
+
+Each case prints its description, key values, and PASS/FAIL/SKIP/ERROR, then a module summary. Same output via:
+
+```sh
+python tests/test_zarchive.py
+```
+
+A short smoke script is also available:
+
+```sh
+python test_smoke.py
+```
+
+Tests that need the native library are skipped if it is not found in `zarchive/_bin` or on the search path.
+
+## Usage
+
+```python
+from zarchive import (
+    Archive,
+    ArchiveReader,
+    ArchiveWriter,
+    GzArchive,
+    SevenZArchive,
+    ZipArchive,
+    extract,
+    format_from_path,
+    format_infos,
+    identify,
+    supported_formats,
+    get_library,
+    resolve_dll_path,
+)
+
+print(resolve_dll_path())
+print(identify(r"C:\data\pack.zip"))
+print(supported_formats())
+print(format_infos())
+print(format_from_path(r"C:\data\pack.7z"))
+
+with ArchiveReader(r"C:\data\pack.tar") as arc:
+    print(arc.namelist())
+    print(arc.read("readme.txt"))
+    arc.extractall(r"C:\data\out")
+
+extract(r"C:\data\pack.gz", r"C:\data\out2")
+
+# Extension selects the format when archive_type is ARCHIVE_AUTO (the default).
+with ArchiveWriter(r"C:\data\new.7z") as writer:
+    writer.writestr("hello.txt", "hello")
+    writer.write(r"C:\data\file.bin", "file.bin")
+
+with GzArchive.create(r"C:\data\new.gz") as writer:
+    writer.writestr("hello.txt", "hello")
+
+with ZipArchive() as zf:
+    print(hex(zf.handle))
+with SevenZArchive() as z7:
+    print(hex(z7.handle))
+
+get_library().deinitialize_all()
+```
+
+`WORKSPACE_PATH` is only needed when running from a source checkout that has not staged `zarchive/_bin`:
+
+```bat
+set WORKSPACE_PATH=d:\Workspace
+```
+
+```sh
+export WORKSPACE_PATH="$HOME/Workspace"
+```
+
+On Windows, the loader adds the DLL directory and CUDA `bin` folders (`CUDA_PATH`, `CUDA_PATH_V*`, or a `PATH` entry that contains `cudart64_12.dll`) via `os.add_dll_directory`. Debug `zCoded` / `zArchive` builds need the CUDA 12 runtime. On Linux it prepends `LD_LIBRARY_PATH`; on macOS, `DYLD_LIBRARY_PATH`.

zarchive_py-0.0.1b3/_bundle_native.py

@@ -0,0 +1,425 @@
+"""Copy the built zArchive shared library and its local deps into zarchive/_bin."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+from _plat import (
+    family_from_wheel_tag,
+    host_family,
+    host_wheel_tag,
+    native_search_dirs,
+    primary_library_names,
+)
+
+_HERE = Path(__file__).resolve().parent
+_BIN_DIR = _HERE / "zarchive" / "_bin"
+_REPO_ROOT = _HERE.parents[2]
+
+_SYSTEM_LIBS = {
+    "kernel32.dll",
+    "user32.dll",
+    "gdi32.dll",
+    "ole32.dll",
+    "oleaut32.dll",
+    "advapi32.dll",
+    "shell32.dll",
+    "shlwapi.dll",
+    "ws2_32.dll",
+    "comctl32.dll",
+    "comdlg32.dll",
+    "cabinet.dll",
+    "ntdll.dll",
+    "bcrypt.dll",
+    "crypt32.dll",
+    "winhttp.dll",
+    "wininet.dll",
+    "imm32.dll",
+    "msvcrt.dll",
+    "ucrtbase.dll",
+    "vcruntime140.dll",
+    "vcruntime140_1.dll",
+    "msvcp140.dll",
+    "rpcrt4.dll",
+    "setupapi.dll",
+    "version.dll",
+    "winmm.dll",
+    "iphlpapi.dll",
+    "dbghelp.dll",
+    "psapi.dll",
+    "powrprof.dll",
+    "wlanapi.dll",
+    "python3.dll",
+    "python311.dll",
+    "python310.dll",
+    "python39.dll",
+    "python38.dll",
+    "libsystem.b.dylib",
+    "libc.so.6",
+    "libm.so.6",
+    "libdl.so.2",
+    "libpthread.so.0",
+    "librt.so.1",
+    "ld-linux-x86-64.so.2",
+    "ld-linux-aarch64.so.1",
+    "libgcc_s.so.1",
+    "libstdc++.so.6",
+    "libcxx.so.1",
+    "libc++.1.dylib",
+    "libSystem.B.dylib",
+}
+
+_SIBLING_PREFIXES = (
+    "zArchive",
+    "zMemLib",
+    "zPlugin",
+    "ude",
+    "SIMDProcessor",
+    "zThread",
+    "zTask",
+    "cpuidt",
+    "zDebug",
+    "zScript",
+    "zCode",
+    "zDataStorage",
+    "zDevEnv",
+    "zPlatform",
+    "zCompiler",
+    "CodeGen",
+    "zMaths",
+    "COMHelper",
+    "zLocale",
+    "zArcMain",
+)
+
+
+def package_bin_dir() -> Path:
+    return _BIN_DIR
+
+
+def _target_family() -> str:
+    override = os.environ.get("ZARCHIVE_WHEEL_PLAT")
+    if override:
+        return family_from_wheel_tag(override)
+    return host_family()
+
+
+def _primary_names() -> list[str]:
+    return primary_library_names(_target_family())
+
+
+def _plat_dirs() -> tuple[str, ...]:
+    return native_search_dirs(_target_family())
+
+
+def _search_roots() -> list[Path]:
+    roots: list[Path] = []
+    workspace = os.environ.get("WORKSPACE_PATH")
+    if workspace:
+        roots.append(Path(workspace))
+        roots.append(Path(workspace) / "lib_main")
+    roots.append(_REPO_ROOT)
+    seen: set[str] = set()
+    unique: list[Path] = []
+    for root in roots:
+        key = os.path.normcase(str(root.resolve())) if root.exists() else os.path.normcase(str(root))
+        if key not in seen:
+            seen.add(key)
+            unique.append(root)
+    return unique
+
+
+def _explicit_native_dir() -> Optional[Path]:
+    raw = os.environ.get("ZARCHIVE_NATIVE_DIR")
+    if not raw:
+        return None
+    path = Path(raw)
+    return path if path.is_dir() else None
+
+
+def find_primary_library() -> Optional[Path]:
+    explicit = _explicit_native_dir()
+    if explicit is not None:
+        for name in _primary_names():
+            candidate = explicit / name
+            if candidate.is_file():
+                return candidate
+        for item in explicit.iterdir():
+            if item.is_file() and item.suffix.lower() in {".dll", ".so", ".dylib"}:
+                if "zarchive" in item.name.lower():
+                    return item
+    for root in _search_roots():
+        for rel in _plat_dirs():
+            directory = root / Path(rel)
+            for name in _primary_names():
+                candidate = directory / name
+                if candidate.is_file():
+                    return candidate
+    return None
+
+
+def _is_system_lib(name: str) -> bool:
+    lowered = name.lower()
+    if lowered in _SYSTEM_LIBS:
+        return True
+    if lowered.startswith("api-ms-win-"):
+        return True
+    if lowered.startswith("vcruntime") or lowered.startswith("msvcp") or lowered.startswith("ucrtbase"):
+        return True
+    if lowered.startswith("libpython"):
+        return True
+    return False
+
+
+def _dumpbin_path() -> Optional[str]:
+    vswhere = Path(os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")) / (
+        "Microsoft Visual Studio/Installer/vswhere.exe"
+    )
+    if not vswhere.is_file():
+        return None
+    try:
+        out = subprocess.check_output(
+            [str(vswhere), "-latest", "-products", "*", "-find", r"**\dumpbin.exe"],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        )
+    except (subprocess.CalledProcessError, OSError):
+        return None
+    fallback = None
+    for line in out.splitlines():
+        path = line.strip()
+        if not path or not Path(path).is_file():
+            continue
+        lowered = path.lower()
+        if lowered.endswith(r"\hostx64\x64\dumpbin.exe"):
+            return path
+        if "dumpbin.exe" in lowered:
+            fallback = path
+    return fallback
+
+
+def _dependents_windows(dll: Path) -> list[str]:
+    dumpbin = _dumpbin_path()
+    if not dumpbin:
+        return []
+    try:
+        out = subprocess.check_output([dumpbin, "/dependents", str(dll)], text=True, stderr=subprocess.STDOUT)
+    except (subprocess.CalledProcessError, OSError):
+        return []
+    names: list[str] = []
+    capture = False
+    for line in out.splitlines():
+        if "Image has the following dependencies" in line:
+            capture = True
+            continue
+        if capture and line.strip() == "Summary":
+            break
+        match = re.match(r"\s+(\S+\.dll)\s*$", line, re.I)
+        if capture and match:
+            names.append(match.group(1))
+    return names
+
+
+def _dependents_unix(library: Path) -> list[str]:
+    if sys.platform == "darwin":
+        cmd = ["otool", "-L", str(library)]
+    else:
+        cmd = ["ldd", str(library)]
+    try:
+        out = subprocess.check_output(cmd, text=True, stderr=subprocess.STDOUT)
+    except (subprocess.CalledProcessError, OSError, FileNotFoundError):
+        return []
+    names: list[str] = []
+    for line in out.splitlines():
+        if sys.platform == "darwin":
+            match = re.search(r"^\s+(\S+\.dylib)", line)
+        else:
+            match = re.search(r"(\S+\.so(?:\.\d+)*)\s+=>\s+(\S+)", line)
+            if match and match.group(2) not in {"not", "found"}:
+                names.append(os.path.basename(match.group(2)))
+                continue
+            match = re.search(r"^\s+(\S+\.so(?:\.\d+)*)", line)
+        if match:
+            names.append(os.path.basename(match.group(1)))
+    return names
+
+
+def _can_inspect_library(library: Path) -> bool:
+    family = _target_family()
+    suffix = library.suffix.lower()
+    if family == "windows":
+        return os.name == "nt" and suffix == ".dll"
+    if family == "macos":
+        return sys.platform == "darwin" and suffix == ".dylib"
+    if family in {"android", "ios"}:
+        return False
+    return os.name != "nt" and sys.platform != "darwin" and ".so" in library.name
+
+
+def _copy_all_shared_from(directory: Path) -> list[Path]:
+    files: list[Path] = []
+    for item in directory.iterdir():
+        if not item.is_file():
+            continue
+        name = item.name.lower()
+        if name.endswith((".dll", ".dylib")) or ".so" in name:
+            files.append(item)
+    return files
+
+
+def _fix_loader_paths() -> None:
+    """Make bundled Unix libraries look next to themselves for siblings."""
+    family = _target_family()
+    if family == "windows" or os.name == "nt":
+        return
+    if family == "macos" and sys.platform == "darwin":
+        for item in _BIN_DIR.iterdir():
+            if not item.is_file() or item.suffix != ".dylib":
+                continue
+            subprocess.run(
+                ["install_name_tool", "-id", f"@loader_path/{item.name}", str(item)],
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            subprocess.run(
+                ["install_name_tool", "-add_rpath", "@loader_path", str(item)],
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        return
+    if family == "linux" and os.name != "nt" and sys.platform != "darwin":
+        patchelf = shutil.which("patchelf")
+        if not patchelf:
+            return
+        for item in _BIN_DIR.iterdir():
+            if not item.is_file() or ".so" not in item.name:
+                continue
+            subprocess.run(
+                [patchelf, "--set-rpath", "$ORIGIN", str(item)],
+                check=False,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+
+
+def _dependents(library: Path) -> list[str]:
+    if os.name == "nt":
+        return _dependents_windows(library)
+    return _dependents_unix(library)
+
+
+def _cuda_runtime_dirs() -> list[Path]:
+    dirs: list[Path] = []
+    for key, value in os.environ.items():
+        if key == "CUDA_PATH" or key.startswith("CUDA_PATH_V"):
+            dirs.append(Path(value) / "bin")
+    for part in os.environ.get("PATH", "").split(os.pathsep):
+        if part and (Path(part) / "cudart64_12.dll").is_file():
+            dirs.append(Path(part))
+    extra = Path(r"E:\ProgramFiles\nVidia\CUDA\v12.6\bin")
+    if extra.is_dir():
+        dirs.append(extra)
+    return dirs
+
+
+def _copy_optional_runtime(name: str, dest: Path) -> None:
+    if (dest / name).is_file():
+        return
+    search: list[Path] = []
+    if name.lower().startswith("cudart"):
+        search.extend(_cuda_runtime_dirs())
+    for directory in search:
+        src = directory / name
+        if src.is_file():
+            shutil.copy2(src, dest / name)
+            print(f"  bundled runtime {name}")
+            return
+
+
+def _sibling_fallback(primary: Path) -> list[Path]:
+    files: list[Path] = []
+    suffix = primary.suffix
+    for item in primary.parent.iterdir():
+        if not item.is_file() or item.suffix.lower() != suffix.lower():
+            continue
+        if any(item.name.startswith(prefix) for prefix in _SIBLING_PREFIXES):
+            files.append(item)
+    return files
+
+
+def _clear_bin_dir() -> None:
+    _BIN_DIR.mkdir(parents=True, exist_ok=True)
+    for item in _BIN_DIR.iterdir():
+        if item.name == ".gitkeep":
+            continue
+        if item.is_file():
+            item.unlink()
+        elif item.is_dir():
+            shutil.rmtree(item)
+
+
+def stage_native_libs() -> Path:
+    """Copy the primary library and local deps into zarchive/_bin. Raises if missing."""
+    primary = find_primary_library()
+    if primary is None:
+        raise FileNotFoundError(
+            "Native zArchive library not found. Build the shared library for this "
+            "platform (Windows: build_native.ps1; Linux/macOS: build_native.sh; "
+            "iOS: build_native_ios.sh; Android: build_native_android.sh), "
+            "or set WORKSPACE_PATH / ZARCHIVE_NATIVE_DIR."
+        )
+
+    _clear_bin_dir()
+    copied: dict[str, Path] = {}
+    source_dir = primary.parent
+    inspect = _can_inspect_library(primary)
+    queue = [primary]
+    if not inspect:
+        queue.extend(_copy_all_shared_from(source_dir))
+
+    while queue:
+        current = queue.pop(0)
+        key = current.name.lower()
+        if key in copied:
+            continue
+        dest = _BIN_DIR / current.name
+        shutil.copy2(current, dest)
+        copied[key] = dest
+        print(f"  bundled {current.name}")
+        if not inspect:
+            continue
+        for dep_name in _dependents(current):
+            if _is_system_lib(dep_name):
+                continue
+            local = source_dir / dep_name
+            if local.is_file():
+                queue.append(local)
+            else:
+                _copy_optional_runtime(dep_name, _BIN_DIR)
+
+    if inspect and len(copied) == 1:
+        for sibling in _sibling_fallback(primary):
+            key = sibling.name.lower()
+            if key not in copied:
+                shutil.copy2(sibling, _BIN_DIR / sibling.name)
+                copied[key] = sibling
+                print(f"  bundled sibling {sibling.name}")
+
+    _fix_loader_paths()
+    print(f"  wheel tag: {host_wheel_tag()}")
+
+    if not any((_BIN_DIR / name).is_file() for name in _primary_names()):
+        raise FileNotFoundError(f"Failed to stage {primary.name} into {_BIN_DIR}")
+    return _BIN_DIR
+
+
+def bundled_primary_names() -> list[str]:
+    return [name for name in _primary_names() if (_BIN_DIR / name).is_file()]