hyperdrone 0.1.0__py3-none-any.whl

hyperdrone/examples/data.py

@@ -0,0 +1,42 @@
+"""Shared data resolution and download helpers for runnable examples."""
+
+import os
+from pathlib import Path
+
+from huggingface_hub import hf_hub_download
+
+from hyperdrone import jit
+
+
+PROCTHOR_FILENAME = "ProcTHOR-Train-1.glb"
+PROCTHOR_REVISION = "db1af73cfd47318df311ed8821caa8e4e0ffeb00"
+
+
+def procthor_scene_path():
+    """Return the local ProcTHOR scene, downloading and caching it when necessary.
+
+    Resolution order: HYPERDRONE_PROCTHOR_PATH, an rl-tools checkout's tests/data,
+    then Hugging Face's versioned cache under <hyperdrone cache>/huggingface.
+    """
+    override = os.environ.get("HYPERDRONE_PROCTHOR_PATH")
+    if override:
+        path = Path(override).expanduser().resolve()
+        if not path.is_file():
+            raise FileNotFoundError(
+                f"hyperdrone: HYPERDRONE_PROCTHOR_PATH does not exist: {path}"
+            )
+        return path
+
+    checkout_path = jit.source_root() / "tests" / "data" / PROCTHOR_FILENAME
+    if checkout_path.is_file():
+        return checkout_path
+
+    return Path(hf_hub_download(
+        repo_id="rl-tools/test-data",
+        repo_type="dataset",
+        filename=PROCTHOR_FILENAME,
+        revision=PROCTHOR_REVISION,
+        cache_dir=jit.cache_root() / "huggingface",
+        local_files_only=bool(os.environ.get("HYPERDRONE_OFFLINE")),
+        library_name="hyperdrone",
+    ))

hyperdrone/examples/drone_flythrough.py

@@ -0,0 +1,142 @@
+"""End-to-end hyperdrone stack: N drones spawned in free space, stepping L2F dynamics and
+rendering their onboard cameras every step. On OptiX + CUDA the camera hand-off is fully
+device-resident (no host synchronization in the loop); the same script runs — slowly — on
+GENERIC + cpu anywhere.
+
+  python -m hyperdrone.examples.drone_flythrough --drones 1024 --steps 200 --width 64 --height 64
+  python -m hyperdrone.examples.drone_flythrough --drones 16 --steps 600 --width 128 --height 128 --video out.mp4
+"""
+import argparse
+import math
+import time
+from pathlib import Path
+
+import numpy as np
+
+from hyperdrone import dynamics, env, render
+
+parser = argparse.ArgumentParser()
+parser.add_argument("-m", "--model", default=None, help="GLB scene (default: procedural room)")
+parser.add_argument("--drones", type=int, default=64)
+parser.add_argument("--steps", type=int, default=100)
+parser.add_argument("--width", type=int, default=64)
+parser.add_argument("--height", type=int, default=64)
+parser.add_argument("--drone-model", default="crazyflie")
+parser.add_argument("--device", default="auto", help="dynamics device (cpu|cuda|auto)")
+parser.add_argument("--save", default=None, help="save the final frame mosaic to this path")
+parser.add_argument("--video", default=None, help="record a video of the onboard views to this path (mp4)")
+parser.add_argument("--video-drones", type=int, default=16, help="number of onboard views tiled into the video")
+parser.add_argument("--video-fps", type=float, default=30.0, help="target video frame rate; steps are strided to play at real time")
+arguments = parser.parse_args()
+
+
+def build_room(rng, num_pillars=32, half=8.0, height=4.0):
+    scene = render.Scene()
+    room = render.Object(name="room")
+
+    def quad(v0, v1, v2, v3, color):
+        vertices = np.array([v0, v1, v2, v3], dtype=np.float32)
+        indices = np.array([[0, 1, 2], [0, 2, 3], [0, 2, 1], [0, 3, 2]], dtype=np.int32)
+        room.add_mesh(render.Mesh(vertices, indices, color=color))
+
+    quad((-half, -half, 0), (half, -half, 0), (half, half, 0), (-half, half, 0), (0.5, 0.5, 0.5))
+    quad((-half, -half, height), (half, -half, height), (half, half, height), (-half, half, height), (0.9, 0.9, 0.9))
+    quad((-half, -half, 0), (half, -half, 0), (half, -half, height), (-half, -half, height), (0.8, 0.3, 0.3))
+    quad((-half, half, 0), (half, half, 0), (half, half, height), (-half, half, height), (0.3, 0.8, 0.3))
+    quad((-half, -half, 0), (-half, half, 0), (-half, half, height), (-half, -half, height), (0.3, 0.3, 0.8))
+    quad((half, -half, 0), (half, half, 0), (half, half, height), (half, -half, height), (0.8, 0.8, 0.3))
+    for _ in range(num_pillars):
+        x, y = rng.uniform(-half * 0.8, half * 0.8, size=2)
+        r = 0.25
+        color = tuple(rng.uniform(0.2, 1.0, size=3))
+        quad((x - r, y - r, 0), (x + r, y - r, 0), (x + r, y - r, height), (x - r, y - r, height), color)
+        quad((x - r, y + r, 0), (x + r, y + r, 0), (x + r, y + r, height), (x - r, y + r, height), color)
+        quad((x - r, y - r, 0), (x - r, y + r, 0), (x - r, y + r, height), (x - r, y - r, height), color)
+        quad((x + r, y - r, 0), (x + r, y + r, 0), (x + r, y + r, height), (x + r, y - r, height), color)
+    scene.add_object(room)
+    scene.add_light(render.SceneLight.directional(direction=(0.3, 0.2, -1.0), color=(1.0, 1.0, 1.0)))
+    scene.add_light(render.SceneLight.directional(direction=(-0.5, 0.4, -0.3), color=(0.4, 0.4, 0.5)))
+    return scene
+
+
+if arguments.model and Path(arguments.model).exists():
+    scene = render.load_scene(arguments.model, shading="medium")
+else:
+    scene = build_room(np.random.default_rng(0))
+
+sim = dynamics.Sim(num_drones=arguments.drones, model=arguments.drone_model, device=arguments.device)
+renderer = render.Renderer(width=arguments.width, height=arguments.height,
+                           num_cameras=arguments.drones, output="rgb", shading="medium")
+world = env.World(scene, sim, renderer)
+
+print(f"backend={renderer.backend} dynamics={sim.device} drones={arguments.drones} "
+      f"device_handoff={'yes' if world._device_handoff else 'no (host cameras)'}")
+
+sampler = env.FreeSpaceSampler(scene, clearance=0.5)
+positions = sampler.sample(arguments.drones, seed=0)
+world.spawn(positions)
+
+# flythrough flight pattern: hover throttle + a small yaw differential (rotor pattern
+# +,-,+,- spins the body around +Z while staying level) + an initial horizontal glide
+# velocity that persists (no aero drag). The yaw differential costs a little collective
+# thrust, so a minimal P-D altitude hold on all four rotors keeps the drones level at
+# their spawn height — panning, gliding onboard views.
+rng = np.random.default_rng(1)
+hover = sim.parameters["hovering_throttle_relative"]
+yaw_rates = rng.uniform(0.015, 0.035, size=arguments.drones) * rng.choice((-1.0, 1.0), size=arguments.drones)
+base_actions = ((2.0 * hover - 1.0)[:, None] + yaw_rates[:, None] * np.array([1.0, -1.0, 1.0, -1.0]))
+glide_angle = rng.uniform(0.0, 2.0 * np.pi, size=arguments.drones)
+glide_speed = rng.uniform(0.2, 0.5, size=arguments.drones)
+velocities = np.zeros((arguments.drones, 3), dtype=np.float32)
+velocities[:, 0] = np.cos(glide_angle) * glide_speed
+velocities[:, 1] = np.sin(glide_angle) * glide_speed
+sim.state["linear_velocity"] = velocities
+altitude_target = positions[:, 2].copy()
+
+
+def flythrough_actions():
+    position_z = sim.state.numpy("position")[:, 2]
+    velocity_z = sim.state.numpy("linear_velocity")[:, 2]
+    correction = 0.4 * (altitude_target - position_z) - 0.25 * velocity_z
+    return np.clip(base_actions + correction[:, None], -1.0, 1.0).astype(np.float32)
+
+video_writer = None
+video_stride = 1
+if arguments.video:
+    import imageio
+
+    video_drones = min(arguments.video_drones, arguments.drones)
+    grid_columns = int(math.ceil(math.sqrt(video_drones)))
+    grid_rows = int(math.ceil(video_drones / grid_columns))
+    # stride steps so the video plays at real time: sim rate (1/dt) down to the target fps
+    video_stride = max(1, round(1.0 / (sim.dt * arguments.video_fps)))
+    video_writer = imageio.get_writer(arguments.video, fps=1.0 / (sim.dt * video_stride))
+
+    def record_frame():
+        views = renderer.frame()[:video_drones, :, :, :3]
+        mosaic = np.zeros((grid_rows * arguments.height, grid_columns * arguments.width, 3), dtype=np.uint8)
+        for view_index in range(video_drones):
+            row, column = divmod(view_index, grid_columns)
+            mosaic[row * arguments.height:(row + 1) * arguments.height,
+                   column * arguments.width:(column + 1) * arguments.width] = views[view_index]
+        video_writer.append_data(mosaic)
+
+start = time.perf_counter()
+for step in range(arguments.steps):
+    world.step(flythrough_actions())
+    if video_writer is not None and step % video_stride == 0:
+        record_frame()
+renderer.synchronize()
+elapsed = time.perf_counter() - start
+
+frames_per_second = arguments.steps * arguments.drones / elapsed
+print(f"{arguments.steps} steps x {arguments.drones} drones in {elapsed:.2f}s "
+      f"({arguments.steps / elapsed:.1f} steps/s, {frames_per_second:.0f} rendered frames/s)")
+
+if video_writer is not None:
+    video_writer.close()
+    print(f"saved {arguments.video}")
+
+if arguments.save:
+    renderer.save_image(arguments.save)
+    print(f"saved {arguments.save}")

hyperdrone/examples/render_procthor.py

@@ -0,0 +1,41 @@
+"""Render the ProcTHOR-Train-1 test scene from an eye-height position inside the house
+(four yaw angles) and show the RGB frames and depth maps with matplotlib."""
+import math
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from hyperdrone import render
+from hyperdrone.examples.data import procthor_scene_path
+
+GLB = procthor_scene_path()
+
+POSITION = np.array([-0.97, -4.42, 1.5])
+YAWS_DEGREES = (150.0, 195.0, 240.0, 285.0)
+
+scene = render.load_scene(GLB, shading="high")
+renderer = render.Renderer(width=320, height=240, num_cameras=len(YAWS_DEGREES), output="rgbd", shading="high")
+renderer.init(scene)
+
+cameras = []
+for yaw_degrees in YAWS_DEGREES:
+    yaw = math.radians(yaw_degrees)
+    look_at = POSITION + np.array([math.cos(yaw), math.sin(yaw), 0.0])
+    cameras.append(renderer.camera(position=POSITION, look_at=look_at, fov=math.radians(80)))
+renderer.set_cameras(np.stack(cameras))
+renderer.render()
+
+frame = renderer.frame()
+depth = renderer.depth()
+
+figure, axes = plt.subplots(2, len(YAWS_DEGREES), figsize=(4 * len(YAWS_DEGREES), 6))
+for camera, yaw_degrees in enumerate(YAWS_DEGREES):
+    axes[0, camera].imshow(frame[camera, :, :, :3])
+    axes[0, camera].set_title(f"yaw {yaw_degrees:.0f}°")
+    depth_image = axes[1, camera].imshow(depth[camera], cmap="viridis")
+    figure.colorbar(depth_image, ax=axes[1, camera], fraction=0.046)
+for axis in axes.flat:
+    axis.axis("off")
+figure.suptitle(f"ProcTHOR-Train-1 — hyperdrone.render ({renderer.backend} backend)")
+figure.tight_layout()
+plt.show()

hyperdrone/jit/__init__.py

@@ -0,0 +1,111 @@
+"""hyperdrone.jit — shared compile-and-cache infrastructure.
+
+A *component* is a native code unit under hyperdrone/_native/<name>/: an optional nanobind
+core module built once per build tree, plus zero or more JIT artifacts — shared libraries
+compiled per compile-time configuration behind a stable extern "C" ABI.
+
+Configs implement the JitConfig protocol: defines() -> {NAME: value} compile definitions,
+canonical() -> stable human-readable string (baked into the artifact and compared on load),
+key() -> short hash naming the artifact. Config files land as configs/<key>.txt inside the
+build tree, one NAME=VALUE line each; the shared hyperdrone_jit.cmake turns each file into
+a MODULE target named <component>_<key>.
+
+Build trees live at <cache>/<component>-<variant>-<tag> (one per component and variant so
+switching variants never invalidates another's cache); all configure/build steps run under
+a per-tree file lock so concurrent processes cannot race one CMake tree.
+"""
+import hashlib
+import importlib.util
+import sys
+from dataclasses import dataclass, field
+
+from . import _build
+from ._workspace import BuildError, build_dir, cache_root, native_root, source_root, workspace_tag
+
+__all__ = [
+    "BuildError",
+    "Component",
+    "build_dir",
+    "cache_root",
+    "canonical_key",
+    "core",
+    "ensure",
+    "native_root",
+    "source_root",
+    "workspace_tag",
+]
+
+_core_modules = {}
+
+
+@dataclass(frozen=True)
+class Component:
+    name: str
+    variant: str
+    core_target: str = None
+    needs_cuda: bool = False
+    cmake_defines: tuple = field(default_factory=tuple)
+    source_dir: str = None  # default: hyperdrone/_native/<name>
+
+
+def canonical_key(canonical):
+    return hashlib.sha1(canonical.encode()).hexdigest()[:16]
+
+
+def _write_config_file(directory, config):
+    import os
+    config_dir = directory / "configs"
+    config_dir.mkdir(exist_ok=True)
+    config_file = config_dir / f"{config.key()}.txt"
+    if config_file.exists():
+        return False
+    lines = "".join(f"{name}={value}\n" for name, value in sorted(config.defines().items()))
+    # per-process staging name: concurrent writers of the same config must not race on one
+    # staging path; the final rename is atomic and idempotent (identical content)
+    staging = config_dir / f"{config.key()}.{os.getpid()}.tmp"
+    staging.write_text(lines)
+    staging.rename(config_file)
+    return True
+
+
+def ensure(component, config):
+    """Build (if necessary) and return the path of the JIT artifact for this config."""
+    directory = _build.ensure_configured(component)
+    fresh = _write_config_file(directory, config)
+    artifact = directory / "jit" / f"{component.name}_{config.key()}.so"
+    if fresh or not artifact.exists():
+        # the target only exists after the configs/ glob is re-run
+        _build.reconfigure(component)
+    _build.build_target(component, f"{component.name}_{config.key()}")
+    if not artifact.exists():
+        raise BuildError(f"hyperdrone: JIT artifact missing after build: {artifact}")
+    return artifact
+
+
+def core(component):
+    """Build (if necessary), load, and cache the component's nanobind core module.
+
+    Extension modules are identified by name process-wide, so one component core can only
+    be loaded for one variant per process (e.g. dynamics on cpu OR cuda, not both)."""
+    if component.core_target is None:
+        raise BuildError(f"hyperdrone: component {component.name} declares no core module")
+    cached = _core_modules.get(component.core_target)
+    if cached is not None:
+        variant, module = cached
+        if variant != component.variant:
+            raise BuildError(
+                f"hyperdrone: {component.core_target} is already loaded for variant "
+                f"'{variant}'; one process can use only one {component.name} variant"
+            )
+        return module
+    directory = _build.build_target(component, component.core_target)
+    matches = sorted(directory.glob(f"{component.core_target}*.so"))
+    matches += sorted(directory.glob(f"{component.core_target}*.dylib"))
+    if not matches:
+        raise BuildError(f"hyperdrone: {component.core_target} module not found in {directory}")
+    specification = importlib.util.spec_from_file_location(component.core_target, matches[0])
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    sys.modules[component.core_target] = module
+    _core_modules[component.core_target] = (component.variant, module)
+    return module

hyperdrone/jit/_build.py

@@ -0,0 +1,94 @@
+import os
+import subprocess
+
+from ._lock import FileLock
+from ._patches import seed_dependencies
+from ._toolchain import environment
+from ._workspace import BuildError, build_dir, dependencies_root, native_root, source_root
+
+BUILD_JOBS = os.environ.get("HYPERDRONE_BUILD_JOBS", "5")
+
+
+def lock(component):
+    directory = build_dir(component)
+    return FileLock(directory.parent / f"{directory.name}.lock")
+
+
+def run(arguments, env):
+    process = subprocess.run(
+        [str(argument) for argument in arguments],
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, env=env,
+    )
+    if process.returncode != 0:
+        tail = "\n".join(process.stdout.splitlines()[-60:])
+        raise BuildError(
+            f"hyperdrone: command failed: {' '.join(str(argument) for argument in arguments)}\n{tail}"
+        )
+    return process.stdout
+
+
+def source_dir(component):
+    if component.source_dir is not None:
+        from pathlib import Path
+        return Path(component.source_dir)
+    return native_root() / component.name
+
+
+def configure(component, directory):
+    import sys
+    seeded = seed_dependencies(directory.name)
+    arguments = [
+        "cmake",
+        "-S", source_dir(component),
+        "-B", directory,
+        "-DCMAKE_BUILD_TYPE=Release",
+        f"-DRLTOOLS_ROOT={source_root()}",
+        f"-DHYPERDRONE_VARIANT={component.variant.upper()}",
+        f"-DHYPERDRONE_NATIVE_ROOT={native_root()}",
+        f"-DPython_EXECUTABLE={sys.executable}",
+        # fully qualified: the rl_tools root CMakeLists cannot append the build-dir
+        # basename to an externally-passed value (non-FORCE cache set)
+        f"-DFETCHCONTENT_BASE_DIR={dependencies_root() / directory.name}",
+    ]
+    for fetch_name, path in sorted(seeded.items()):
+        arguments.append(f"-DFETCHCONTENT_SOURCE_DIR_{fetch_name}={path}")
+    for name, value in component.cmake_defines:
+        arguments.append(f"-D{name}={value}")
+    if os.environ.get("HYPERDRONE_OFFLINE"):
+        arguments.append("-DRL_TOOLS_OFFLINE_BUILD=ON")
+    run(arguments, environment(component))
+
+
+def ensure_configured(component):
+    directory = build_dir(component)
+    if (directory / "CMakeCache.txt").exists():
+        return directory
+    with lock(component):
+        if not (directory / "CMakeCache.txt").exists():
+            directory.mkdir(parents=True, exist_ok=True)
+            try:
+                configure(component, directory)
+            except BaseException:
+                # a failed configure must not leave a tree that looks configured; the
+                # FetchContent state lives in .dependencies/ and survives for the retry
+                import shutil
+                shutil.rmtree(directory, ignore_errors=True)
+                raise
+    return directory
+
+
+def build_target(component, target):
+    directory = ensure_configured(component)
+    if os.environ.get("HYPERDRONE_SKIP_BUILD"):
+        return directory
+    with lock(component):
+        run(["cmake", "--build", directory, "--target", target, "-j", BUILD_JOBS],
+            environment(component))
+    return directory
+
+
+def reconfigure(component):
+    directory = ensure_configured(component)
+    with lock(component):
+        run(["cmake", directory], environment(component))
+    return directory

hyperdrone/jit/_lock.py

@@ -0,0 +1,23 @@
+"""Advisory file lock serializing configure/build on one build tree across processes
+(vectorized RL workloads routinely spawn many workers that would otherwise race the same
+CMake tree). POSIX flock; a Windows port replaces this module with an msvcrt equivalent."""
+import fcntl
+import os
+
+
+class FileLock:
+    def __init__(self, path):
+        self._path = path
+        self._handle = None
+
+    def __enter__(self):
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._handle = os.open(self._path, os.O_CREAT | os.O_RDWR, 0o644)
+        fcntl.flock(self._handle, fcntl.LOCK_EX)
+        return self
+
+    def __exit__(self, *exception):
+        fcntl.flock(self._handle, fcntl.LOCK_UN)
+        os.close(self._handle)
+        self._handle = None
+        return False

hyperdrone/jit/_patches.py

@@ -0,0 +1,95 @@
+"""Quarantine for third-party dependency workarounds.
+
+Seeding: FetchContent sources land in <source_root>/.dependencies/<build-dir-basename>.
+New build trees are seeded from any already-populated sibling so offline machines work and
+locally patched trees are not silently re-cloned. Seeded sources are handed to CMake via
+FETCHCONTENT_SOURCE_DIR_<NAME> overrides (per-dependency, so everything else still fetches
+normally); those overrides skip FetchContent's populate step, so patch scripts that
+normally run at populate time are applied here explicitly.
+"""
+import re
+import shutil
+import subprocess
+
+from ._workspace import source_root
+
+# FetchContent name -> source directory basename
+SEEDED_SOURCES = {
+    "OWL": "owl-src",
+    "STB": "stb-src",
+    "NLOHMANN_JSON": "nlohmann_json-src",
+}
+
+# FetchContent name -> cmake file declaring its GIT_TAG; seeds are validated against the
+# declared pin so a repin upstream can never be shadowed by a stale seeded checkout
+PINNED_SOURCES = {"OWL": "cmake/optional/optix.cmake"}
+
+
+def declared_pin(fetch_name):
+    relative = PINNED_SOURCES.get(fetch_name)
+    if relative is None:
+        return None
+    declaration = source_root() / relative
+    if not declaration.exists():
+        return None
+    match = re.search(
+        r"FetchContent_Declare\(\s*" + fetch_name + r"\b.*?GIT_TAG\s+([0-9a-fA-F]{7,40})",
+        declaration.read_text(), re.IGNORECASE | re.DOTALL,
+    )
+    return match.group(1) if match else None
+
+
+def checkout_head(tree):
+    result = subprocess.run(
+        ["git", "-C", str(tree), "rev-parse", "HEAD"], capture_output=True, text=True,
+    )
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def matches_pin(tree, pin):
+    return pin is None or checkout_head(tree) == pin
+
+# cmake -P scripts under <source_root>/cmake/patches, applied to the named FetchContent
+# source dir; each script is idempotent and documents its upstream-removal condition.
+# (Empty since the OWL PinnedHostMem fix landed upstream with the 978a6664 repin.)
+PATCH_SCRIPTS = {}
+
+
+def apply_patch_scripts(seeded):
+    for fetch_name, (script_name, root_variable) in PATCH_SCRIPTS.items():
+        tree = seeded.get(fetch_name)
+        script = source_root() / "cmake" / "patches" / script_name
+        if tree is not None and script.exists():
+            subprocess.run(
+                ["cmake", f"-D{root_variable}={tree}", "-P", str(script)],
+                check=True, capture_output=True,
+            )
+
+
+def seed_dependencies(build_dir_name):
+    """Copy FetchContent sources from a populated sibling; returns {FETCH_NAME: path} for
+    every seeded (or already present) source directory."""
+    from ._workspace import dependencies_root
+    dependency_root = dependencies_root()
+    target_base = dependency_root / build_dir_name
+    donors = sorted(
+        candidate for candidate in dependency_root.glob("*")
+        if candidate.is_dir() and candidate.name != build_dir_name and (candidate / "owl-src").is_dir()
+    ) if dependency_root.is_dir() else []
+    seeded = {}
+    for fetch_name, source_name in SEEDED_SOURCES.items():
+        pin = declared_pin(fetch_name)
+        target = target_base / source_name
+        if target.exists() and not matches_pin(target, pin):
+            shutil.rmtree(target)
+        if not target.exists():
+            for donor in donors:
+                source = donor / source_name
+                if source.is_dir() and matches_pin(source, pin):
+                    target_base.mkdir(parents=True, exist_ok=True)
+                    shutil.copytree(source, target, symlinks=True)
+                    break
+        if target.is_dir():
+            seeded[fetch_name] = target
+    apply_patch_scripts(seeded)
+    return seeded

hyperdrone/jit/_toolchain.py

@@ -0,0 +1,13 @@
+import os
+import shutil
+from pathlib import Path
+
+
+def environment(component):
+    env = os.environ.copy()
+    if component.needs_cuda and "CUDACXX" not in env and "CMAKE_CUDA_COMPILER" not in env:
+        for candidate in ("/usr/local/cuda/bin/nvcc", shutil.which("nvcc")):
+            if candidate and Path(candidate).exists():
+                env["CUDACXX"] = str(candidate)
+                break
+    return env

hyperdrone/jit/_workspace.py

@@ -0,0 +1,70 @@
+import hashlib
+import os
+import sysconfig
+from pathlib import Path
+
+
+class BuildError(RuntimeError):
+    pass
+
+
+def cache_root():
+    env = os.environ.get("HYPERDRONE_CACHE_DIR")
+    if env:
+        return Path(env)
+    return Path.home() / ".cache" / "hyperdrone"
+
+
+def package_root():
+    return Path(__file__).resolve().parents[1]
+
+
+def native_root():
+    return package_root() / "_native"
+
+
+def source_root():
+    """rl-tools source root: env override, enclosing repository checkout, vendored tree."""
+    env = os.environ.get("HYPERDRONE_RLTOOLS_ROOT")
+    if env:
+        root = Path(env).resolve()
+        if not (root / "include" / "rl_tools").is_dir():
+            raise BuildError(
+                f"hyperdrone: HYPERDRONE_RLTOOLS_ROOT={root} is not an rl-tools source root "
+                "(include/rl_tools missing)"
+            )
+        return root
+    candidate = package_root()
+    for _ in range(8):
+        if (candidate / "include" / "rl_tools").is_dir():
+            return candidate
+        candidate = candidate.parent
+    vendored = package_root() / "_vendor" / "rl-tools"
+    if (vendored / "include" / "rl_tools").is_dir():
+        return vendored
+    raise BuildError(
+        "hyperdrone: rl-tools sources not found (no enclosing repository checkout and no "
+        "vendored tree; set HYPERDRONE_RLTOOLS_ROOT to an rl-tools source root)"
+    )
+
+
+def dependencies_root():
+    """FetchContent sources live next to the checkout for repo builds (shared with other
+    build dirs, seedable); for vendored installs they go to the cache — site-packages may
+    be read-only and must never accumulate build state."""
+    root = source_root()
+    try:
+        root.relative_to(package_root())
+        return cache_root() / ".dependencies"
+    except ValueError:
+        return root / ".dependencies"
+
+
+def workspace_tag():
+    from .. import __version__
+    fingerprint = f"{source_root()}|{sysconfig.get_config_var('SOABI')}|{__version__}"
+    return hashlib.sha1(fingerprint.encode()).hexdigest()[:8]
+
+
+def build_dir(component):
+    return cache_root() / f"{component.name}-{component.variant}-{workspace_tag()}"