[Wheel] Support self-contained package and Git-source installs

[StafaH]

Description

Make the aggregate Isaac Lab package self-contained and directly installable from a Git revision.

The wheel previously exposed the canonical core package through a nested isaaclab/source/isaaclab/isaaclab tree and a runtime isaaclab.__path__ mutation. In addition, downstream projects could not use the repository as a normal Git dependency: pointing a package manager at source/isaaclab built only the dependency-free leaf package and omitted repository-level runtime resources such as apps/isaaclab.python.kit.

This PR:

• installs the canonical core modules directly in the top-level isaaclab package;
• resolves bundled resources consistently in source checkouts and installed packages;
• exposes tools/wheel_builder as a PEP 517 package source;
• stages Git-source builds through the same aggregate package assembly used by release wheels;
• preserves the aggregate wheel’s top-level main() and bootstrap_kernel() compatibility APIs;
• routes the installed console command through the compatibility dispatcher, including --generate-vscode-settings;
• retains the root pyproject.toml as the single source of truth for third-party dependencies and extras;
• bundles the sibling isaaclab_* packages, Kit experience files, package data, and template resources; and
• keeps the existing tools/wheel_builder/build.sh workflow by sharing its staging implementation.

No dependencies are added to the individual Isaac Lab subpackage manifests, and no public Python API is changed.

Downstream use cases

External task repositories and applications can now depend on one aggregate isaaclab package at an unreleased commit or tag. They no longer need:

• a sibling Isaac Lab checkout at a fixed local path;
• separate source declarations for every isaaclab_* package;
• a copied list of Isaac Lab's transitive third-party dependencies; or
• a downstream workaround for the missing apps/isaaclab.python.kit resource.

A downstream uv project can declare:

[project]
dependencies = ["isaaclab"]

[tool.uv.sources]
isaaclab = {
  git = "https://github.com/isaac-sim/IsaacLab.git",
  rev = "<commit-or-tag>",
  subdirectory = "tools/wheel_builder",
}

Pinning rev to a commit or tag makes the complete Isaac Lab code and dependency metadata reproducible in the downstream lockfile. A branch such as develop also works, with the usual behavior that a future lockfile update may select a newer revision.

This is particularly useful for downstream task packages that need changes from develop before the next Isaac Lab wheel release, and for CI systems that should resolve the complete environment without provisioning a separate source checkout.

Implementation

• The aggregate wheel uses a conventional flat isaaclab package instead of extending isaaclab.__path__ at runtime. The resource resolver lives in the conventionally named isaaclab.paths module.
• The compatibility dispatcher now lives in the canonical package, so source and aggregate builds share isaaclab.__main__; the generated console entry point targets that dispatcher rather than bypassing legacy options.
• A small PEP 517 backend implements wheel, sdist, and metadata hooks for Git-source consumers.
• Package staging was moved from shell commands into a shared Python helper used by both the PEP 517 backend and the existing build script.
• The generated aggregate metadata continues to read dependencies and extras from the repository root and removes only the isaaclab_* workspace self-references because those packages are bundled in the artifact.
• The installed package includes apps/*.kit, so asset-root discovery and AppLauncher use the same experience files as a source checkout.

Type of change

• Bug fix (non-breaking change which fixes the installed package layout)
• New feature (Git-source installation for downstream projects)

Release backport

• Backport this pull request to the active release branch after it merges into develop

Validation

• Resolved and installed a fresh uv project whose only dependency was isaaclab from a pinned Git revision and the tools/wheel_builder subdirectory.
• Verified imports for isaaclab, isaaclab_assets, isaaclab_newton, isaaclab_rl, and isaaclab_tasks from that fresh environment.
• Verified the Git-built installation contains apps/isaaclab.python.kit, resolves the default asset root, and runs isaaclab --help.
• Built both a wheel and an sdist through the new PEP 517 entry point.
• Built the wheel through the existing tools/wheel_builder/build.sh entry point.
• Ran focused CLI, wheel-metadata, and asset tests (77 passed), including regressions for the legacy VS Code option and top-level compatibility APIs.
• Inspected the wheel to verify that core modules use the flat layout, isaaclab/paths.py replaces _paths.py, the console entry point targets isaaclab.__main__:main, and the Kit experience files are included.
• Ruff, formatting, and all applicable pre-commit hooks passed. The repository-wide changelog hook reports pre-existing fragment differences on the branch; this PR includes the required isaaclab changelog fragments.

Screenshots

Not applicable.

Checklist

• I have read and understood the contribution guidelines
• I have run the applicable pre-commit checks
• I have documented the Git-source installation path
• My changes generate no new runtime warnings
• I have added tests that exercise the aggregate build and installed resource layout
• I have added a changelog fragment under source/isaaclab/changelog.d/
• My name already exists in CONTRIBUTORS.md

[greptile-apps]

Greptile Summary

The PR flattens the wheel’s core isaaclab package, centralizes source-versus-wheel resource-root resolution, and points the generated console script at the canonical CLI.

• Copies canonical core modules directly into the wheel’s top-level package and removes the nested package copy.
• Uses ISAACLAB_ROOT for application, asset, CLI, and benchmark resources.
• Adds smoke coverage for the flattened archive and runtime package path.
• The direct console entry point drops the retained legacy VS Code settings option.

Confidence Score: 4/5

The console-entry regression should be fixed before merging because an installed-wheel command that previously generated VS Code settings now fails argument parsing.

The flattened package and resource-root changes align with the staged source and wheel layouts, but directly targeting isaaclab.cli:cli bypasses the compatibility dispatcher that implements --generate-vscode-settings.

Files Needing Attention: tools/wheel_builder/gen_pyproject.py and tools/wheel_builder/res/main.py

Important Files Changed

Filename	Overview
tools/wheel_builder/build.sh	Flattens the canonical core package into the staged top-level package while retaining bundled runtime resources.
source/isaaclab/isaaclab/_paths.py	Introduces shared resource-root detection for source checkouts and flattened wheel installations.
tools/wheel_builder/gen_pyproject.py	Points the console script directly at the canonical CLI, bypassing the retained compatibility option in __main__.
source/isaaclab/test/install_ci/misc/test_wheel_builder_smoke.py	Verifies the flat archive and package path but exercises python -m isaaclab, not the changed console-script dispatch behavior.
source/isaaclab/isaaclab/app/app_launcher.py	Resolves bundled Kit experiences through the shared installation root.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Source[Canonical core package] --> Stage[Wheel staging]
  Resources[apps / source / tools] --> Stage
  Stage --> Flat[Top-level isaaclab package]
  Flat --> Root[ISAACLAB_ROOT resolution]
  Root --> Runtime[CLI, AppLauncher, assets, benchmarks]
  Entry[Console entry point] --> CLI[isaaclab.cli:cli]

Loading

_{Reviews (1): Last reviewed commit: "Flatten the installed Isaac Lab package" | Re-trigger Greptile}

[isaaclab-review-bot]

Isaac Lab Review Bot

The wheel flattening and centralized resource-root resolution are coherent, but replacing the wheel initializer removes two existing top-level callables and therefore changes the installed API despite the PR’s non-breaking claim.

• Design and architecture: Staging the canonical package directly under isaaclab removes the runtime __path__ mutation cleanly, and centralizing resource lookup through ISAACLAB_ROOT avoids layout-specific path arithmetic. The flattened package should retain compatibility shims for behavior previously supplied by the wheel wrapper.
• API: The installed package loses isaaclab.main and isaaclab.bootstrap_kernel when res/__init__.py is no longer copied. In particular, bootstrap_kernel was explicitly documented as retained for backwards compatibility. These symbols need a deprecation-compatible migration rather than immediate removal.
• Implementation: The build ordering, direct isaaclab.cli:cli console entry point, and flat-layout smoke coverage are consistent with the packaging goal. However, the smoke test does not cover the removed top-level callables; thin delegating compatibility exports in the canonical initializer would preserve the existing installed-package surface.

Minor fixes needed. Posted 1 actionable finding inline.

Automated review; human maintainers own approval decisions.

[kellyguo11]

run-ci

[diegoferigo-rai]

Thanks @StafaH for this, a long due fix! Flattening the package and resolving resources from isaaclab/_paths.py::ISAACLAB_ROOT drops the __path__ mutation, so downstream I no longer need any custom patch and can package plain upstream. The isaaclab console entry point now resolves from the flat package, and isaaclab --help/train/play run on CPU without IsaacSim 🚀

[StafaH]

run-ci