[Wheel] Flatten the installed Isaac Lab package

[StafaH]

Description

Install the core Isaac Lab modules directly in the wheel top-level isaaclab package instead of exposing isaaclab/source/isaaclab/isaaclab by mutating isaaclab.__path__.

This change:

• stages the canonical core package in a conventional flat layout;
• removes the wheel-only wrapper initializer and its unconditional package-path mutation;
• resolves bundled runtime resources consistently in source checkouts and installed wheels;
• points the console entry point directly at the canonical CLI; and
• adds a wheel smoke regression test for both the archive layout and runtime package path.

No public API changes or new dependencies are introduced.

Type of change

• Bug fix (non-breaking change which fixes an issue)

Release backport

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

Validation

• uv run --with pip env -u VIRTUAL_ENV python -m pytest source/isaaclab/test/install_ci/misc/test_wheel_builder_smoke.py -q (12 passed)
• Focused CLI and asset tests (71 passed)
• Built and inspected the wheel: core modules are flat, the nested core tree is absent, and isaaclab.__path__ contains one package directory
• Installed the wheel in an isolated environment without Isaac Sim and verified imports, resources, python -m isaaclab, and isaaclab --help
• Installed with Isaac Sim 6.0.1 and verified AppLauncher, SimulationContext, and a real headless simulator startup/shutdown
• All applicable formatting and pre-commit hooks passed. The repository-wide changelog check currently reports unrelated pre-existing fragment issues in isaaclab_ov, isaaclab_rl, and isaaclab_teleop; this PR includes its required isaaclab fragment.

Screenshots

Not applicable.

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks
• No documentation changes are required for this internal packaging fix
• My changes generate no new warnings
• I have added tests that prove my fix is effective
• 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}

[greptile-apps]

Console compatibility dispatch is bypassed

When an installed-wheel user runs isaaclab --generate-vscode-settings, the changed entry point calls isaaclab.cli:cli directly, which rejects the legacy option instead of generating the settings.

Suggested change

	lines.append('isaaclab = "isaaclab.cli:cli"')
	lines.append('isaaclab = "isaaclab.__main__:main"')

[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.

[isaaclab-review-bot]

🟡 Warning · Api — Wheel drops top-level main and bootstrap_kernel

The wheel no longer installs res/__init__.py, so the installed isaaclab package loses the top-level main() (previously the isaaclab:main entry-point target) and bootstrap_kernel(), which the deleted file explicitly retained for backwards compatibility. Wheel users doing from isaaclab import main or bootstrap_kernel now fail. Either keep thin delegating shims in the canonical initializer or record the removal and migration path in the changelog fragment.

[kellyguo11]

run-ci