proot: let users specify a custom proot binary via PD_PROOT_BIN

Adds an env var override for the proot executable, following the same
override-and-validate pattern already used for --emulator. Consolidates
the three previously-duplicated "shutil.which(proot) or proot" lookups
into one arch.get_proot_bin() helper.

Author: sylirre

README.md

@@ -120,6 +120,9 @@ On startup the tool verifies that `proot` is available. If it isn't:
   install it via `pkg install -y -q proot`.
 - Otherwise, an install hint is printed and the program exits.
 
+Set `PD_PROOT_BIN` to use a custom `proot` executable instead of the
+PATH lookup; see the environment variables table below.
+
 PRoot-Distro also refuses to run inside another `proot` (nested proot
 is not supported by `proot` itself) and prints a warning if launched
 as the `root` user.
@@ -1233,6 +1236,7 @@ paths sit under `$BASE_CACHE_DIR` (`$RUNTIME_DIR/cache` on Termux,
 | `XDG_DATA_HOME` | On non-Termux hosts, base for `$XDG_DATA_HOME/proot-distro/`. Defaults to `~/.local/share`. |
 | `XDG_CACHE_HOME` | On non-Termux hosts, base for `$XDG_CACHE_HOME/proot-distro/`. Defaults to `~/.cache`. |
 | `PD_DOCKER_AUTH` | Credentials for pulling and pushing Docker/OCI images. Must be in `username:password` or `username:PAT` format (colon required). Sent as HTTP Basic auth to the registry's token endpoint to obtain a scoped bearer token. Takes effect for `install`, `build` (`FROM` base-image pulls), and `push` (with `pull,push` scope). |
+| `PD_PROOT_BIN` | Absolute path to a custom `proot` executable, used in place of the PATH lookup for `login`, `run`, and `build` RUN steps. Must point at an existing, executable file or the command exits with an error. |
 | `PD_FORCE_NO_COLORS` | When set to any value, disables ANSI colors in PRoot-Distro's own output. |
 | `PROOT_VERBOSE` | Inherited and forwarded to `proot` for debugging. Skipped in `--minimal` mode. |
 | `COLUMNS` | Fallback terminal width for `--help` rendering. |

proot_distro/arch.py

@@ -186,6 +186,23 @@ def normalize_arch(arch: str):
 }
 
 
+def get_proot_bin() -> str:
+    """Return the proot executable to invoke, honoring PD_PROOT_BIN.
+
+    A set override is validated like --emulator: it must point at an
+    existing, executable file, or the process exits with an error.
+    Unset falls back to the existing PATH lookup for "proot".
+    """
+    override = os.environ.get("PD_PROOT_BIN")
+    if override:
+        if not os.path.isfile(override) or not os.access(override, os.X_OK):
+            crit_error(f"PD_PROOT_BIN '{override}' is not found or not "
+                       f"executable.")
+            sys.exit(1)
+        return override
+    return shutil.which("proot") or "proot"
+
+
 def get_emulator_args(
     dist_arch: str, device_arch: str, emulator_override: str = ""
 ) -> list:

proot_distro/cli.py

@@ -37,6 +37,7 @@
 
 from proot_distro.constants import IS_TERMUX, PROGRAM_NAME
 from proot_distro.message import C, msg, set_quiet, crit_error
+from proot_distro.arch import get_proot_bin
 from proot_distro.parser import (
     ALIAS_TO_CANONICAL, REQUIRED_ARGS, build_parser,
 )
@@ -125,6 +126,10 @@ def ensure_proot_installed() -> None:
     `build`, which defers this check until it knows the Dockerfile
     actually contains a RUN-family instruction.
     """
+    if os.environ.get("PD_PROOT_BIN"):
+        get_proot_bin()  # validates, crit_error()+exit(1) if bad
+        return
+
     if shutil.which("proot") is not None:
         return
 

proot_distro/commands/login/__init__.py

@@ -32,7 +32,6 @@
 import json
 import os
 import shlex
-import shutil
 import sys
 
 from proot_distro.constants import (
@@ -48,6 +47,7 @@
     detect_installed_arch,
     get_device_cpu_arch,
     get_emulator_args,
+    get_proot_bin,
 )
 from proot_distro.sysdata import setup_fake_sysdata
 from proot_distro.locking import ContainerLock
@@ -422,7 +422,7 @@ def _command_login_inner(container_name: str, args, lock) -> None:
                    f"architecture-specific binaries.")
         sys.exit(1)
 
-    proot_bin = shutil.which("proot") or "proot"
+    proot_bin = get_proot_bin()
     proot_args = build_proot_args(
         proot_bin=proot_bin,
         rootfs=rootfs,

proot_distro/helpers/build_engine/run_step.py

@@ -31,7 +31,6 @@
 import os
 import signal
 import subprocess
-import shutil
 
 from proot_distro.constants import (
     DEFAULT_PATH_ENV,
@@ -43,7 +42,7 @@
 )
 from proot_distro.message import log_info
 from proot_distro.arch import (
-    ARCH_UNAME_M, get_device_cpu_arch, get_emulator_args,
+    ARCH_UNAME_M, get_device_cpu_arch, get_emulator_args, get_proot_bin,
 )
 from proot_distro.sysdata import setup_fake_sysdata, fake_proc_bindings
 from proot_distro.helpers.build_cache import (
@@ -148,7 +147,7 @@ def _run_extra_inputs(engine):
 def _exec_proot(engine, stage, command, stdin_input):
     """Invoke proot against *stage*'s rootfs to execute *command*."""
     rootfs = stage.rootfs_dir
-    proot_bin = shutil.which("proot") or "proot"
+    proot_bin = get_proot_bin()
     proot_args = [proot_bin]
 
     emu_args = get_emulator_args(